fix(api): make adapter non-optional within branch and annotate pipeline for mypy

app/bootstrap.py

@@ -0,0 +1,7 @@
+try:
+    from dotenv import load_dotenv
+
+    load_dotenv()
+except Exception:
+    # optional: silently continue if python-dotenv is not installed
+    pass

app/main.py

@@ -1,11 +1,30 @@
-from dotenv import load_dotenv
+import os
+import time
+from typing import Protocol, runtime_checkable, cast
 
-load_dotenv()
+from fastapi import FastAPI, Request, Response, HTTPException
+from fastapi.responses import PlainTextResponse
 
-from fastapi import FastAPI  # noqa: E402
-from app.routers import nl2sql  # noqa: E402
+from app.routers import nl2sql
 
-# restore previous uploaded DB map
+# Prometheus
+from prometheus_client import (
+    Counter,
+    Histogram,
+    CollectorRegistry,
+    generate_latest,
+    CONTENT_TYPE_LATEST,
+)
+
+
+@runtime_checkable
+class HasPing(Protocol):
+    """Minimal interface for adapters that support a connectivity check."""
+
+    def ping(self) -> None: ...
+
+
+# ---- Optionally restore uploaded DB map ----
 try:
     from app.routers.nl2sql import _load_db_map
 
@@ -15,16 +34,78 @@ except Exception as e:
 
 app = FastAPI(
     title="NL2SQL Copilot Prototype",
-    version="0.1.0",
-    description="Natural Language -> SQL Copilot API",
+    version=os.getenv("APP_VERSION", "0.1.0"),
+    description="Convert natural language to safe & verified SQL",
 )
 
 app.include_router(nl2sql.router, prefix="/api/v1")
 
+# ---- Prometheus metrics ----
+REGISTRY: CollectorRegistry = CollectorRegistry()
+
+REQUEST_COUNT = Counter(
+    "http_requests_total",
+    "Total HTTP requests",
+    ["path", "method", "status_code"],
+    registry=REGISTRY,
+)
+
+REQUEST_LATENCY = Histogram(
+    "http_request_latency_seconds",
+    "Request latency",
+    ["path", "method"],
+    registry=REGISTRY,
+)
+
 
-@app.get("/healthz")
-def health_check():
-    return {"status": "ok"}
+@app.middleware("http")
+async def metrics_middleware(request: Request, call_next):
+    start = time.perf_counter()
+    response: Response = await call_next(request)
+    elapsed = time.perf_counter() - start
+
+    # Use route path if available, else raw path (typed guard for mypy)
+    route = request.scope.get("route")
+    path = (
+        route.path
+        if (route is not None and hasattr(route, "path"))
+        else request.url.path
+    )
+
+    REQUEST_COUNT.labels(
+        path=path, method=request.method, status_code=str(response.status_code)
+    ).inc()
+    REQUEST_LATENCY.labels(path=path, method=request.method).observe(elapsed)
+    return response
+
+
+# --- Liveness (super light) ---
+@app.get("/healthz", response_class=PlainTextResponse, tags=["system"])
+def healthz() -> str:
+    return "ok"
+
+
+# --- Readiness (checks DB/env lightly) ---
+@app.get("/readyz", response_class=PlainTextResponse, tags=["system"])
+def readyz() -> str:
+    mode = os.getenv("DB_MODE", "sqlite").lower()
+    try:
+        if mode == "postgres":
+            from adapters.db.postgres_adapter import PostgresAdapter
+
+            dsn = os.environ["POSTGRES_DSN"]
+            # Call ping inline; avoid cross-branch variable typing
+            cast(HasPing, PostgresAdapter(dsn)).ping()
+        else:
+            from adapters.db.sqlite_adapter import SQLiteAdapter
+
+            db_path = os.getenv("SQLITE_DB_PATH", "data/chinook.db")
+            cast(HasPing, SQLiteAdapter(db_path)).ping()
+
+        # if not os.getenv("PROXY_API_KEY"): pass
+        return "ready"
+    except Exception:
+        raise HTTPException(status_code=503, detail="not ready")
 
 
 @app.get("/")
@@ -34,4 +115,11 @@ def root():
 
 @app.get("/health")
 def health():
+    # You might want to replace the placeholders with real checks later.
     return {"status": "ok", "db": "connected", "llm": "reachable", "uptime_sec": 123.4}
+
+
+@app.get("/metrics", tags=["system"])
+def metrics():
+    data = generate_latest(REGISTRY)
+    return Response(content=data, media_type=CONTENT_TYPE_LATEST)

app/routers/nl2sql.py

@@ -285,11 +285,13 @@ async def upload_db(file: UploadFile = File(...)):
 @router.post("", name="nl2sql_handler")
 def nl2sql_handler(request: NL2SQLRequest):
     db_id = getattr(request, "db_id", None)
-    adapter: Optional[Union[PostgresAdapter, SQLiteAdapter]] = None
 
     # 1) Pick pipeline (+ optional per-request adapter)
+    pipeline: Pipeline
     if db_id:
-        adapter = _select_adapter(db_id)
+        adapter = _select_adapter(db_id)  # returns PostgresAdapter | SQLiteAdapter
+        # If _select_adapter could theoretically return None, uncomment the next line:
+        # assert adapter is not None, "adapter must be set when db_id is provided"
         pipeline = _build_pipeline(adapter)
         derived_preview_val: str = _derive_schema_preview(adapter)
     else:
@@ -299,7 +301,6 @@ def nl2sql_handler(request: NL2SQLRequest):
     # 2) Resolve schema_preview
     provided_preview_any: Any = getattr(request, "schema_preview", None)
     provided_preview: Optional[str] = cast(Optional[str], provided_preview_any)
-
     final_preview: str = provided_preview or derived_preview_val
 
     # 3) Run pipeline

requirements.txt

@@ -9,6 +9,7 @@ pytest==8.3.3
 python-dotenv==1.1.1
 openai==2.6.1
 psycopg[binary]~=3.2
+prometheus-client>=0.20.0
 ruff
 gradio
 sqlalchemy

tests/test_health_and_metrics.py

@@ -0,0 +1,19 @@
+# tests/test_health_and_metrics.py
+from fastapi.testclient import TestClient
+from app.main import app
+
+client = TestClient(app)
+
+
+def test_healthz_ok():
+    r = client.get("/healthz")
+    assert r.status_code == 200
+    assert r.text == "ok"
+
+
+def test_metrics_exposes_prometheus():
+    # Hit one endpoint to bump counters
+    client.get("/healthz")
+    r = client.get("/metrics")
+    assert r.status_code == 200
+    assert "http_requests_total" in r.text