Sync from GitHub main @ bb85132be0e6ce9fb3b72683c3321f8a7056eeb6

app/dependencies.py

@@ -20,6 +20,8 @@ def get_nl2sql_service() -> NL2SQLService:
 def get_cache() -> NL2SQLCache:
     """
     Singleton in-memory cache for NL2SQL responses.
-    TTL is intentionally short; this is a per-process best-effort cache.
+
+    TTL is loaded from Settings (NL2SQL_CACHE_TTL_SEC).
     """
-    return NL2SQLCache(ttl=15.0)
+    settings = get_settings()
+    return NL2SQLCache(ttl=float(settings.cache_ttl_sec))

app/routers/nl2sql.py

@@ -5,7 +5,7 @@ from dataclasses import asdict, is_dataclass
 import os
 from pathlib import Path
 import uuid
-from typing import Any, Dict, Optional, Tuple, cast
+from typing import Any, Dict, Optional, cast
 import hashlib
 import logging
 
@@ -50,68 +50,12 @@ def require_api_key(key: Optional[str] = Security(api_key_header)):
         raise HTTPException(status_code=401, detail="invalid API key")
 
 
-####################################
-# ---- Simple in-memory cache for NL→SQL responses ----
-
-# Cache TTL and max size from centralized settings
-_CACHE_TTL = settings.cache_ttl_sec
-_CACHE_MAX = settings.cache_max_entries
-_CACHE: Dict[Tuple[str, str, str], Tuple[float, Dict[str, Any]]] = {}
-
-
-def _norm_q(s: str) -> str:
-    """Normalize a user query for cache key purposes."""
-    return (s or "").strip().lower()
-
-
-def _schema_key(preview: str) -> str:
-    """Hash the schema preview so we do not store huge strings in the cache key."""
-    return hashlib.md5((preview or "").encode()).hexdigest()
-
-
-def _ck(
-    db_id: Optional[str],
-    query: str,
-    schema_preview: str,
-) -> str:
-    """
-    Build a stable cache key for (db_id, query, schema_preview).
-
-    We keep the external cache API string-based, and hash the
-    potentially large schema_preview to avoid huge dictionary keys.
-    """
-    # Normalize db_id
-    db_part = db_id or "__default__"
-
-    # Build a single string seed
-    seed = f"{db_part}\n{query}\n{schema_preview}"
-
-    # Short, deterministic key
-    return hashlib.sha1(seed.encode("utf-8")).hexdigest()
-
-
-def _cache_gc(now: float) -> None:
-    """
-    Garbage-collect cache entries by TTL and max size.
-    """
-    # TTL eviction
-    for k, (ts, _) in list(_CACHE.items()):
-        if now - ts > _CACHE_TTL:
-            _CACHE.pop(k, None)
-
-    # Size eviction (naive FIFO-style)
-    while len(_CACHE) > _CACHE_MAX:
-        _CACHE.pop(next(iter(_CACHE)), None)
-
-
-####################################
-
 router = APIRouter(prefix="/nl2sql")
 
 # -------------------------------
 # Config / Defaults
 # -------------------------------
-DB_MODE = settings.db_mode.lower()  # "sqlite" or "postgres"
+DB_MODE = settings.db_mode.lower()
 
 # Runtime upload storage for SQLite DBs
 _DB_UPLOAD_DIR = settings.db_upload_dir
@@ -127,29 +71,14 @@ logger.debug(
 )
 
 
-# -------------------------------
-# Schema preview endpoint
-# -------------------------------
-
-
 @router.get("/schema")
 def schema_endpoint(
     db_id: Optional[str] = None,
     svc: NL2SQLService = Depends(get_nl2sql_service),
 ):
-    """
-    Return a lightweight schema preview string for the given DB.
-
-    - If db_id is provided, service will resolve the uploaded DB.
-    - If not, service falls back to the default DB.
-    - In postgres mode, caller must usually provide schema_preview explicitly.
-    Domain errors (AppError subclasses) are handled by the global exception handler.
-    This endpoint only wraps truly unexpected errors into a generic HTTP 500
-    """
     try:
         preview = svc.get_schema_preview(db_id=db_id, override=None)
     except AppError:
-        # Let the global AppError handler deal with it.
         raise
     except Exception as exc:
         logger.exception("Unexpected error in schema_endpoint", exc_info=exc)
@@ -176,15 +105,6 @@ def _to_dict(obj: Any) -> Any:
 
 
 def _round_trace(t: Any) -> Dict[str, Any]:
-    """
-    Normalize a trace entry (dict or StageTrace-like object) for API/UI:
-
-    - stage: str (required)
-    - duration_ms: int (rounded)
-    - summary: optional (pass-through if exists)
-    - notes: optional
-    - token_in/out, cost_usd: pass-through if present
-    """
     if isinstance(t, dict):
         stage = t.get("stage", "?")
         ms = t.get("duration_ms", 0)
@@ -275,26 +195,23 @@ def health():
     return {"status": "ok", "version": settings.app_version}
 
 
-# -------------------------------
-# Main NL2SQL endpoint
-# -------------------------------
+def _ck(db_id: Optional[str], query: str, schema_preview: str) -> str:
+    db_part = db_id or "__default__"
+    seed = f"{db_part}\n{query}\n{schema_preview}"
+    return hashlib.sha1(seed.encode("utf-8")).hexdigest()
 
 
-@router.post("", name="nl2sql_handler", dependencies=[Depends(require_api_key)])
+@router.post(
+    "",
+    name="nl2sql_handler",
+    dependencies=[Depends(require_api_key)],
+    response_model=NL2SQLResponse | ClarifyResponse,
+)
 def nl2sql_handler(
     request: NL2SQLRequest,
     svc: NL2SQLService = Depends(get_nl2sql_service),
     cache: NL2SQLCache = Depends(get_cache),
-) -> NL2SQLResponse | ClarifyResponse | Dict[str, Any]:
-    """
-    Main NL→SQL handler.
-
-    Flow:
-    - Resolve schema preview (client override or derived from DB).
-    - Check in-memory cache (db_id + query + schema hash).
-    - Run the pipeline through NL2SQLService.
-    - Map FinalResult to API response or HTTP error.
-    """
+) -> NL2SQLResponse | ClarifyResponse:
     db_id = getattr(request, "db_id", None)
 
     # ---- schema preview ----
@@ -320,7 +237,10 @@ def nl2sql_handler(
     cache_key = _ck(db_id, request.query, final_preview)
     cached_payload = cache.get(cache_key)
     if cached_payload is not None:
-        return cached_payload
+        # Cache stores dicts; convert back to response models for type safety.
+        if isinstance(cached_payload, dict) and cached_payload.get("ambiguous") is True:
+            return ClarifyResponse.model_validate(cached_payload)
+        return NL2SQLResponse.model_validate(cached_payload)
 
     # ---- pipeline execution via service ----
     try:
@@ -354,8 +274,7 @@ def nl2sql_handler(
 
     # ---- ambiguity path → 200 with clarification questions ----
     if result.ambiguous:
-        qs = result.questions or []
-        return ClarifyResponse(ambiguous=True, questions=qs)
+        return ClarifyResponse(questions=(result.questions or []))
 
     # ---- error path: contract-based mapping (Phase 3) ----
     if (not result.ok) or result.error:

app/schemas.py

@@ -1,6 +1,7 @@
-from pydantic import BaseModel
 from typing import List, Optional, Any, Dict
 
+from pydantic import BaseModel, Field
+
 
 class NL2SQLRequest(BaseModel):
     query: str
@@ -21,16 +22,16 @@ class TraceModel(BaseModel):
 
 
 class NL2SQLResponse(BaseModel):
-    ambiguous: bool
+    ambiguous: bool = False
     sql: Optional[str] = None
     rationale: Optional[str] = None
-    traces: List[Dict[str, Any]] = []
-    result: Dict[str, Any] = {}
+    traces: List[Dict[str, Any]] = Field(default_factory=list)
+    result: Dict[str, Any] = Field(default_factory=dict)
 
 
 class ClarifyResponse(BaseModel):
     ambiguous: bool = True
-    questions: List[str]
+    questions: List[str] = Field(default_factory=list)
 
 
 class ErrorResponse(BaseModel):

scripts/verify_metrics_wiring.py

@@ -0,0 +1,244 @@
+#!/usr/bin/env python3
+
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Any, Iterable
+
+ROOT = Path(__file__).resolve().parents[1]
+
+PROMETHEUS_FILE = ROOT / "adapters" / "metrics" / "prometheus.py"
+RULES_FILE = ROOT / "infra" / "prometheus" / "rules.yml"
+DASHBOARD_DIR = ROOT / "infra" / "grafana" / "dashboards"
+
+# Extract metric names from prometheus client constructors:
+# Counter("x", ...), Gauge("x", ...), Histogram("x", ...), Summary("x", ...)
+METRIC_CTOR_RE = re.compile(r'\b(?:Counter|Gauge|Histogram|Summary)\(\s*"([^"]+)"')
+
+# Fallback in case a metric is defined via keyword arg name="..."
+METRIC_NAME_KW_RE = re.compile(r'\bname\s*=\s*"([^"]+)"')
+
+# PromQL token pattern
+PROMQL_TOKEN_RE = re.compile(r"([a-zA-Z_:][a-zA-Z0-9_:]*)")
+
+PROMQL_KEYWORDS_AND_FUNCS = {
+    # aggregations / funcs
+    "sum",
+    "rate",
+    "increase",
+    "irate",
+    "avg",
+    "min",
+    "max",
+    "count",
+    "count_values",
+    "stddev",
+    "stdvar",
+    "bottomk",
+    "topk",
+    "quantile",
+    "histogram_quantile",
+    "clamp_min",
+    "clamp_max",
+    "abs",
+    "round",
+    "floor",
+    "ceil",
+    "scalar",
+    "vector",
+    "sort",
+    "sort_desc",
+    "label_replace",
+    "label_join",
+    "time",
+    # modifiers / keywords
+    "by",
+    "without",
+    "offset",
+    "bool",
+    "on",
+    "ignoring",
+    "group_left",
+    "group_right",
+    # literals / common
+    "true",
+    "false",
+    "nan",
+    "inf",
+}
+
+PROMQL_LABEL_KEYS = {
+    "le",
+    "job",
+    "instance",
+    "stage",
+    "status",
+    "outcome",
+    "hit",
+    "ok",
+}
+
+# label values that appear in your rules/dashboards
+PROMQL_COMMON_LABEL_VALUES = {
+    "attempt",
+    "success",
+    "failed",
+    "ok",
+    "error",
+    "true",
+    "false",
+}
+
+# time units that can show up e.g. [5m], [10s]
+PROMQL_TIME_UNITS = {"ms", "s", "m", "h", "d", "w", "y"}
+
+
+def extract_defined_metrics() -> set[str]:
+    text = PROMETHEUS_FILE.read_text(encoding="utf-8")
+    defined = set(METRIC_CTOR_RE.findall(text))
+    defined |= set(METRIC_NAME_KW_RE.findall(text))
+    return defined
+
+
+def _collect_promql_from_rules_yml(text: str) -> list[str]:
+    """
+    Extract only PromQL expressions from rules.yml:
+    - expr: <single line>
+    - expr: |  (multiline indented block)
+    - expr: >  (multiline indented block)
+    """
+    lines = text.splitlines()
+    exprs: list[str] = []
+
+    i = 0
+    while i < len(lines):
+        line = lines[i]
+        stripped = line.lstrip()
+        if not stripped.startswith("expr:"):
+            i += 1
+            continue
+
+        indent = len(line) - len(stripped)
+        rest = stripped[len("expr:") :].strip()
+
+        # Case 1: expr: <single-line>
+        if rest and rest not in {"|", ">"}:
+            exprs.append(rest)
+            i += 1
+            continue
+
+        # Case 2: expr: | or expr: > or expr: (empty) with following indented block
+        i += 1
+        block_lines: list[str] = []
+        while i < len(lines):
+            nxt = lines[i]
+            nxt_stripped = nxt.lstrip()
+            nxt_indent = len(nxt) - len(nxt_stripped)
+
+            # Stop when indentation returns to expr level (or less)
+            if nxt_stripped and nxt_indent <= indent:
+                break
+
+            # Keep blank lines inside block as separators
+            block_lines.append(nxt_stripped)
+            i += 1
+
+        expr = "\n".join(block_lines).strip()
+        if expr:
+            exprs.append(expr)
+
+    return exprs
+
+
+def _collect_promql_from_dashboard_json(obj: Any) -> Iterable[str]:
+    """
+    Recursively collect PromQL strings from Grafana dashboard JSON.
+    Common keys are: "expr" (Prometheus target), sometimes "query".
+    """
+    if isinstance(obj, dict):
+        for k, v in obj.items():
+            if k in {"expr", "query"} and isinstance(v, str):
+                yield v
+            else:
+                yield from _collect_promql_from_dashboard_json(v)
+    elif isinstance(obj, list):
+        for item in obj:
+            yield from _collect_promql_from_dashboard_json(item)
+
+
+def extract_promql_sources() -> list[str]:
+    sources: list[str] = []
+
+    # rules.yml
+    rules_text = RULES_FILE.read_text(encoding="utf-8")
+    sources.extend(_collect_promql_from_rules_yml(rules_text))
+
+    # dashboards
+    for path in DASHBOARD_DIR.glob("**/*.json"):
+        data = json.loads(path.read_text(encoding="utf-8"))
+        sources.extend(list(_collect_promql_from_dashboard_json(data)))
+
+    return sources
+
+
+def extract_metrics_from_promql(promql: str) -> set[str]:
+    tokens = set(PROMQL_TOKEN_RE.findall(promql))
+    out: set[str] = set()
+    for t in tokens:
+        if t in PROMQL_KEYWORDS_AND_FUNCS:
+            continue
+        if t in PROMQL_LABEL_KEYS:
+            continue
+        if t in PROMQL_COMMON_LABEL_VALUES:
+            continue
+        if t in PROMQL_TIME_UNITS:
+            continue
+        if t.isupper():
+            continue
+        out.add(t)
+    return out
+
+
+def is_generated_from_defined(metric: str, defined: set[str]) -> bool:
+    """
+    Accept generated series from client libraries:
+      - Histogram: <base>_bucket, <base>_sum, <base>_count, <base>_created
+      - Summary:   <base>_sum, <base>_count, <base>_created
+    """
+    generated_suffixes = ("_bucket", "_sum", "_count", "_created")
+    for base in defined:
+        for suf in generated_suffixes:
+            if metric == f"{base}{suf}":
+                return True
+    return False
+
+
+def main() -> None:
+    defined = extract_defined_metrics()
+    promql_sources = extract_promql_sources()
+
+    used: set[str] = set()
+    for q in promql_sources:
+        used |= extract_metrics_from_promql(q)
+
+    # Ignore recorded series (contain ':') — derived metrics are allowed.
+    missing = sorted(
+        m
+        for m in used
+        if ":" not in m
+        and m not in defined
+        and not is_generated_from_defined(m, defined)
+    )
+
+    if missing:
+        print("❌ Metrics used but not defined (raw):")
+        for m in missing:
+            print(f"  - {m}")
+        sys.exit(1)
+
+    print("✅ Metrics wiring OK — no drift detected.")
+
+
+if __name__ == "__main__":
+    main()