Sync from GitHub main @ 843379ca43f29dcb9d317fdd2bf6d608bcbc8a7e

README.md

@@ -25,6 +25,35 @@ A live interactive demo is available on Hugging Face Spaces: 👉 [**Try the Dem
   <img src="docs/assets/screenshots/demo_list_albums_total_sales.png" width="700">
 </p>
 
+
+
+## Quickstart (Local)
+
+### 1) Install
+```bash
+make install
+```
+
+### 2) Run API (Terminal 1)
+```bash
+make demo-up
+```
+
+### 3) Smoke (Terminal 2)
+```bash
+make demo-smoke
+```
+
+### 4) Observability stack (optional)
+```bash
+make infra-up
+```
+
+Then (optional Prometheus snapshot):
+```bash
+make demo-metrics
+```
+
 ---
 
 ## Why this exists

adapters/db/base.py

@@ -8,7 +8,10 @@ class DBAdapter(Protocol):
     dialect: str
 
     def preview_schema(self, limit_per_table: int = 0) -> str:
-        """Generate a readable summary of the database schema with optional sample rows per table."""
+        """Human-friendly schema preview (may include types, bullets, samples)."""
+
+    def derive_schema_preview(self) -> str:
+        """LLM/eval schema preview. Format: table(col1, col2, ...) one per line."""
 
     def execute(self, sql: str) -> Tuple[List[Tuple[Any, ...]], List[str]]:
         """Execute a SELECT query and return (rows, columns)."""

adapters/db/postgres_adapter.py

@@ -83,3 +83,27 @@ class PostgresAdapter(DBAdapter):
                 # psycopg returns rows like ("Seq Scan on ...",)
                 plan_lines: List[str] = [str(r[0]) for r in rows if r and len(r) >= 1]
                 return plan_lines
+
+    def derive_schema_preview(self) -> str:
+        """
+        LLM/eval schema preview. One line per table: table(col1, col2, ...)
+        """
+        with psycopg.connect(self.dsn) as conn:
+            with conn.cursor() as cur:
+                cur.execute(
+                    """
+                    SELECT table_name, column_name
+                    FROM information_schema.columns
+                    WHERE table_schema = 'public'
+                    ORDER BY table_name, ordinal_position;
+                    """
+                )
+                rows = cur.fetchall() or []
+
+        tables: dict[str, list[str]] = {}
+        for table, col in rows:
+            if table and col:
+                tables.setdefault(table, []).append(col)
+
+        lines = [f"{t}({', '.join(cols)})" for t, cols in tables.items() if cols]
+        return "\n".join(lines)

adapters/db/sqlite_adapter.py

@@ -21,15 +21,44 @@ class SQLiteAdapter(DBAdapter):
             raise FileNotFoundError(f"SQLite DB does not exist: {self.path}")
         with sqlite3.connect(f"file:{self.path}?mode=ro", uri=True) as conn:
             cur = conn.cursor()
-            cur.execute("SELECT name FROM sqlite_master WHERE type='table';")
+            cur.execute(
+                "SELECT name FROM sqlite_master WHERE type='table' "
+                "AND name NOT LIKE 'sqlite_%' ORDER BY name;"
+            )
             tables = [t[0] for t in cur.fetchall()]
             lines = []
             for t in tables:
-                cur.execute(f"PRAGMA table_info({t});")
+                safe_t = t.replace("'", "''")
+                cur.execute(f"PRAGMA table_info('{safe_t}');")
                 cols = [f"{c[1]}:{c[2]}" for c in cur.fetchall()]
                 lines.append(f"- {t} ({', '.join(cols)})")
             return "\n".join(lines)
 
+    def derive_schema_preview(self) -> str:
+        """Return a stable schema preview string for prompts/evaluation."""
+        # Keep this aligned with eval runners: one line per table: Table(col1, col2, ...)
+        if not self.path.exists():
+            raise FileNotFoundError(f"SQLite DB does not exist: {self.path}")
+
+        with sqlite3.connect(f"file:{self.path}?mode=ro", uri=True) as conn:
+            cur = conn.cursor()
+            cur.execute(
+                "SELECT name FROM sqlite_master "
+                "WHERE type='table' AND name NOT LIKE 'sqlite_%' "
+                "ORDER BY name;"
+            )
+            tables = [t[0] for t in cur.fetchall()]
+            lines: List[str] = []
+            for t in tables:
+                safe_t = t.replace("'", "''")
+                cur.execute(f"PRAGMA table_info('{safe_t}');")
+                cols = [row[1] for row in cur.fetchall() if row and row[1]]
+                if cols:
+                    lines.append(f"{t}({', '.join(cols)})")
+                else:
+                    lines.append(f"{t}()")
+            return "\n".join(lines)
+
     def execute(self, sql: str) -> Tuple[List[Tuple[Any, ...]], List[str]]:
         if not self.path.exists():
             raise FileNotFoundError(f"SQLite DB does not exist: {self.path}")

app/services/nl2sql_service.py

@@ -1,26 +1,25 @@
 from __future__ import annotations
 
-import sqlite3
+import os
 from dataclasses import dataclass
-from typing import Any, Optional
 from pathlib import Path
+from typing import Any, Optional
 
-from nl2sql.pipeline import FinalResult
-from nl2sql.pipeline_factory import pipeline_from_config_with_adapter
-from adapters.db.sqlite_adapter import SQLiteAdapter
 from adapters.db.postgres_adapter import PostgresAdapter
+from adapters.db.sqlite_adapter import SQLiteAdapter
 from adapters.metrics.prometheus import PrometheusMetrics
-
 from app import state
-from app.settings import Settings
 from app.errors import (
     AppError,
     DbNotFound,
-    SchemaRequired,
-    SchemaDeriveError,
     PipelineConfigError,
     PipelineRunError,
+    SchemaDeriveError,
+    SchemaRequired,
 )
+from app.settings import Settings
+from nl2sql.pipeline import FinalResult
+from nl2sql.pipeline_factory import pipeline_from_config_with_adapter
 
 Adapter = Any  # You can replace this with a Protocol later
 
@@ -54,48 +53,16 @@ class NL2SQLService:
                 raise DbNotFound(f"Could not resolve DB for db_id={db_id!r}")
             return SQLiteAdapter(path=path)
 
-        default_path = self.settings.default_sqlite_path
+        # Allow tests (and deployments) to override the default DB path at runtime
+        # even if Settings was instantiated before env vars were patched.
+        default_path = (
+            os.getenv("DEFAULT_SQLITE_PATH") or self.settings.default_sqlite_path
+        )
         if not Path(default_path).exists():
             raise DbNotFound(f"SQLite database path does not exist: {default_path!r}")
 
         return SQLiteAdapter(path=default_path)
 
-    def _introspect_sqlite_schema(self, adapter: Adapter) -> str:
-        """
-        Build a lightweight textual schema preview for a SQLite database.
-
-        This is a straight port of the previous sqlite3 logic, but contained
-        inside the service instead of the router.
-        """
-        db_path = getattr(adapter, "db_path", None) or getattr(adapter, "path", None)
-        if not db_path:
-            raise RuntimeError(
-                "SQLite adapter must expose a .db_path or .path attribute"
-            )
-
-        if not Path(db_path).exists():
-            raise FileNotFoundError(f"SQLite database path does not exist: {db_path}")
-
-        lines: list[str] = []
-        conn = sqlite3.connect(db_path)
-        try:
-            cur = conn.cursor()
-            cur.execute(
-                "SELECT name FROM sqlite_master WHERE type='table' "
-                "AND name NOT LIKE 'sqlite_%' ORDER BY name"
-            )
-            tables = [row[0] for row in cur.fetchall()]
-
-            for table in tables:
-                cur.execute(f"PRAGMA table_info({table})")
-                cols = [row[1] for row in cur.fetchall()]
-                if cols:
-                    lines.append(f"{table}({', '.join(cols)})")
-        finally:
-            conn.close()
-
-        return "\n".join(lines)
-
     def get_schema_preview(
         self,
         db_id: Optional[str],
@@ -117,7 +84,7 @@ class NL2SQLService:
 
         try:
             adapter = self._select_adapter(db_id)
-            return self._introspect_sqlite_schema(adapter)
+            return adapter.derive_schema_preview()
         except DbNotFound:
             raise
         except Exception as exc:

scripts/smoke_api.py

@@ -0,0 +1,117 @@
+"""Portable smoke request for NL2SQL Copilot.
+
+- Ensures a demo SQLite DB exists under /tmp/nl2sql_dbs/smoke_demo.sqlite
+- Uploads it to the API
+- Runs a few representative queries
+- Exits non-zero on failure (so Make/CI can trust it)
+
+Env:
+  API_BASE: base URL of API (default: http://127.0.0.1:8000)
+  API_KEY:  API key header value (default: dev-key)
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from pathlib import Path
+
+import requests
+
+
+API_BASE = os.getenv("API_BASE", "http://127.0.0.1:8000").rstrip("/")
+API_KEY = os.getenv("API_KEY", "dev-key")
+
+DB_DIR = Path("/tmp/nl2sql_dbs")
+DB_PATH = DB_DIR / "smoke_demo.sqlite"
+
+
+def _ensure_demo_db(path: Path) -> None:
+    """Delegate to scripts/smoke_run.py if available; otherwise fail."""
+    # Your repo already has scripts/smoke_run.py which creates the DB deterministically.
+    from smoke_run import ensure_demo_db  # type: ignore
+
+    ensure_demo_db(path)
+
+
+def _upload_db_and_get_id(path: Path) -> str:
+    url = f"{API_BASE}/api/v1/nl2sql/upload_db"
+    headers = {"X-API-Key": API_KEY}
+    with path.open("rb") as f:
+        resp = requests.post(url, headers=headers, files={"file": f}, timeout=30)
+    if resp.status_code != 200:
+        raise RuntimeError(f"Upload failed: {resp.status_code} {resp.text[:400]}")
+    data = resp.json()
+    db_id = data.get("db_id")
+    if not db_id:
+        raise RuntimeError(f"Invalid upload response: {data}")
+    return str(db_id)
+
+
+def _run_query(db_id: str, query: str) -> dict:
+    url = f"{API_BASE}/api/v1/nl2sql"
+    headers = {"X-API-Key": API_KEY, "Content-Type": "application/json"}
+    payload = {"db_id": db_id, "query": query}
+
+    t0 = time.time()
+    resp = requests.post(url, headers=headers, json=payload, timeout=60)
+    dt_ms = int(round((time.time() - t0) * 1000))
+
+    out: dict = {}
+    try:
+        out = resp.json()
+    except Exception:
+        out = {"raw": resp.text}
+
+    return {"status": resp.status_code, "latency_ms": dt_ms, "body": out}
+
+
+def main() -> int:
+    DB_DIR.mkdir(parents=True, exist_ok=True)
+
+    try:
+        _ensure_demo_db(DB_PATH)
+    except Exception as e:
+        print(f"❌ Failed to create demo DB: {e}")
+        return 2
+
+    try:
+        db_id = _upload_db_and_get_id(DB_PATH)
+    except Exception as e:
+        print(f"❌ Failed to upload demo DB: {e}")
+        return 3
+
+    checks = [
+        ("How many artists are there?", True),
+        ("Which customer spent the most based on total invoice amount?", True),
+        ("DELETE FROM users;", False),  # must be blocked
+    ]
+
+    ok_all = True
+    for q, should_succeed in checks:
+        r = _run_query(db_id=db_id, query=q)
+        status = r["status"]
+        body = r["body"]
+        print(f"\nQuery: {q}")
+        print(f"HTTP {status} | {r['latency_ms']} ms")
+        print(json.dumps(body, indent=2)[:800])
+
+        if should_succeed:
+            if status != 200:
+                ok_all = False
+        else:
+            # A safety violation should not be a 200
+            if status == 200:
+                ok_all = False
+
+    if ok_all:
+        print("\n✅ demo-smoke passed")
+        return 0
+
+    print("\n❌ demo-smoke failed (see output above)")
+    return 4
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/smoke_metrics.py

@@ -0,0 +1,56 @@
+"""Portable Prometheus metrics validation for NL2SQL Copilot.
+
+This script does NOT require jq.
+It queries Prometheus HTTP API and prints a small snapshot.
+
+Pre-req:
+  - API is running and you've already exercised it (e.g. via smoke_api.py)
+  - Prometheus is reachable
+
+Env:
+  PROMETHEUS_URL (default: http://127.0.0.1:9090)
+"""
+
+from __future__ import annotations
+
+import os
+import json
+from typing import Any, Dict
+
+import requests
+
+
+PROM = os.getenv("PROMETHEUS_URL", "http://127.0.0.1:9090").rstrip("/")
+
+
+def prom_query(expr: str) -> Dict[str, Any]:
+    url = f"{PROM}/api/v1/query"
+    resp = requests.get(url, params={"query": expr}, timeout=15)
+    resp.raise_for_status()
+    return resp.json()
+
+
+def main() -> int:
+    queries = [
+        "nl2sql:pipeline_success_ratio",
+        "nl2sql:stage_p95_ms",
+    ]
+
+    print("📊 Prometheus snapshot")
+    print(f"PROMETHEUS_URL={PROM}")
+
+    ok = True
+    for q in queries:
+        try:
+            out = prom_query(q)
+            print(f"\nQuery: {q}")
+            print(json.dumps(out, indent=2)[:1200])
+        except Exception as e:
+            ok = False
+            print(f"❌ Prometheus query failed for {q}: {e}")
+
+    return 0 if ok else 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/smoke_metrics.sh

@@ -1,52 +1,9 @@
+#!/usr/bin/env bash
 set -euo pipefail
 
-API_BASE=${API_BASE:-"http://127.0.0.1:8000"}
-API_KEY=${API_KEY:-"dev-key"}
-PROM=${PROMETHEUS_URL:-"http://127.0.0.1:9090"}
-TMP_DB="/tmp/nl2sql_dbs/smoke_demo.sqlite"
+# Deprecated: prefer `python scripts/smoke_metrics.py` (portable, no jq required).
 
-echo "🧪 Running NL2SQL smoke metrics validation..."
-echo "API_BASE=$API_BASE"
-echo "PROMETHEUS_URL=$PROM"
-echo "TMP_DB=$TMP_DB"
+PROMETHEUS_URL=${PROMETHEUS_URL:-"http://127.0.0.1:9090"}
+export PROMETHEUS_URL
 
-# --- 1. Make sure the DB exists ---
-if [ ! -f "$TMP_DB" ]; then
-  echo "⚙️  Creating demo database via smoke_run.py..."
-  python scripts/smoke_run.py || {
-    echo "❌ smoke_run.py failed to create demo DB."
-    exit 1
-  }
-else
-  echo "✅ Found existing DB at $TMP_DB"
-fi
-
-# --- 2. Upload DB and capture db_id ---
-echo "⬆️  Uploading demo DB..."
-DB_ID=$(curl -s -X POST "$API_BASE/api/v1/nl2sql/upload_db" \
-  -H "X-API-Key: $API_KEY" \
-  -F "file=@${TMP_DB}" | jq -r '.db_id')
-
-if [ "$DB_ID" = "null" ] || [ -z "$DB_ID" ]; then
-  echo "❌ Failed to upload DB or get db_id."
-  exit 1
-fi
-echo "✅ Uploaded DB_ID: $DB_ID"
-
-# --- 3. Run a few API smoke queries ---
-echo "🚀 Sending test queries..."
-curl -s -X POST "$API_BASE/api/v1/nl2sql" \
-  -H "Content-Type: application/json" -H "X-API-Key: $API_KEY" \
-  -d "{\"db_id\":\"$DB_ID\",\"query\":\"How many artists are there?\"}" | jq .
-
-curl -s -X POST "$API_BASE/api/v1/nl2sql" \
-  -H "Content-Type: application/json" -H "X-API-Key: $API_KEY" \
-  -d "{\"db_id\":\"$DB_ID\",\"query\":\"Which customer spent the most?\"}" | jq .
-
-# --- 4. Collect metrics snapshot from Prometheus ---
-echo "📊 Checking Prometheus metrics..."
-curl -s "$PROM/api/v1/query?query=nl2sql:pipeline_success_ratio" | jq .
-
-curl -s "$PROM/api/v1/query?query=nl2sql:stage_p95_ms" | jq .
-
-echo "✅ Smoke metrics check completed."
+python scripts/smoke_metrics.py