Merge master into main for Hugging Face

.dockerignore

@@ -0,0 +1,17 @@
+__pycache__/
+*.py[cod]
+*.log
+*.xlsx
+
+.git
+.gitignore
+.gitattributes
+
+.env
+.env.*
+
+venv/
+.venv/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/

.gitignore

@@ -0,0 +1,20 @@
+__pycache__/
+*.py[cod]
+*.log
+
+# Virtual envs
+venv/
+.venv/
+
+# Local environment / secrets
+.env
+.env.*
+
+# Data files
+*.xlsx
+
+# OS / editor junk
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/

Dockerfile

@@ -0,0 +1,24 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# Install system dependencies (if needed, extend this)
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install Python deps
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy application code
+COPY . .
+
+ENV PYTHONUNBUFFERED=1
+
+# Hugging Face Spaces pass the port via the PORT env var
+ENV PORT=7860
+EXPOSE 7860
+
+# Start FastAPI app with uvicorn
+CMD ["sh", "-c", "uvicorn app:app --host 0.0.0.0 --port ${PORT}"]

README.md

@@ -1,10 +1,21 @@
----
-title: Sqlbot
-emoji: 🔥
-colorFrom: red
-colorTo: gray
+title: sqlbot
+emoji: 🧠
+colorFrom: blue
+colorTo: green
 sdk: docker
-pinned: false
+app_port: 7860
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+## sqlbot — AI SQL Analyst
+
+This Space runs a FastAPI app that lets you ask natural-language questions about your PostgreSQL database and get:
+
+- Generated SQL
+- Executed query results
+- Explanations and insights
+
+### Deployment notes
+
+- The backend FastAPI app is defined in `app.py`.
+- The Docker image is built from `Dockerfile` and exposes port `7860`.
+- The app connects to PostgreSQL via the `DATABASE_URL` environment variable (configured in the Space settings, e.g., a Neon connection string).

ai/__init__.py

@@ -0,0 +1 @@
+# ai package

ai/groq_setup.py

@@ -0,0 +1,34 @@
+"""DSPy language model setup for Groq and OpenAI.
+
+Provides a factory function to create the right LM based on the
+user-selected provider.
+"""
+
+import dspy
+import config
+
+
+def get_lm(provider: str = "groq") -> dspy.LM:
+    """Return a configured DSPy language-model instance.
+
+    Parameters
+    ----------
+    provider : "groq" | "openai"
+    """
+    if provider == "openai":
+        lm = dspy.LM(
+            model=f"openai/{config.OPENAI_MODEL}",
+            api_key=config.OPENAI_API_KEY,
+            max_tokens=4096,
+            temperature=0.2,
+        )
+    else:  # default: groq
+        lm = dspy.LM(
+            model=f"groq/{config.GROQ_MODEL}",
+            api_key=config.GROQ_API_KEY,
+            max_tokens=4096,
+            temperature=0.2,
+        )
+
+    dspy.configure(lm=lm)
+    return lm

ai/pipeline.py

@@ -0,0 +1,248 @@
+"""Main DSPy reasoning pipeline — optimized for speed.
+
+Reduced from 9 stages to 4 LLM calls in the happy path:
+1. AnalyzeAndPlan  (question understanding + schema analysis + query planning)
+2. SQLGeneration
+3. SQLCritiqueAndFix  (one pass; only retries on failure)
+4. InterpretAndInsight  (interpretation + insights in one call)
+"""
+
+import json
+import logging
+import re
+from typing import Any
+
+import dspy
+
+from ai.groq_setup import get_lm
+from ai.signatures import (
+    AnalyzeAndPlan,
+    SQLGeneration,
+    SQLRepair,
+    InterpretAndInsight,
+)
+from ai.validator import validate_sql, check_sql_against_schema
+from db.schema import format_schema
+from db.relationships import format_relationships
+from db.profiler import get_data_profile
+from db.executor import execute_sql
+
+logger = logging.getLogger(__name__)
+
+MAX_REPAIR_RETRIES = 2
+
+
+class SQLAnalystPipeline:
+    """End-to-end reasoning pipeline: question → SQL → results → insights."""
+
+    def __init__(self, provider: str = "groq"):
+        self.provider = provider
+        self._lm = get_lm(provider)
+
+        # DSPy predict modules
+        self.analyze = dspy.Predict(AnalyzeAndPlan)
+        self.generate_sql = dspy.Predict(SQLGeneration)
+        self.interpret = dspy.Predict(InterpretAndInsight)
+        self.repair = dspy.Predict(SQLRepair)
+
+    # ── public API ──────────────────────────────────────────────────────
+
+    def run(self, question: str) -> dict[str, Any]:
+        """Run the full pipeline and return {sql, data, answer, insights}."""
+        schema_str = format_schema()
+        rels_str = format_relationships()
+        profile_str = get_data_profile()
+
+        # 1. Analyze & Plan (single LLM call replaces 3 former stages)
+        logger.info("Stage 1 — Analyze & Plan")
+        plan = self.analyze(
+            question=question,
+            schema_info=schema_str,
+            relationships=rels_str,
+            data_profile=profile_str,
+        )
+
+        plan_text = (
+            f"Intent: {plan.intent}\n"
+            f"Tables: {plan.relevant_tables}\n"
+            f"Columns: {plan.relevant_columns}\n"
+            f"Joins: {plan.join_conditions}\n"
+            f"Where: {plan.where_conditions}\n"
+            f"Aggregations: {plan.aggregations}\n"
+            f"Group By: {plan.group_by}\n"
+            f"Order By: {plan.order_by}\n"
+            f"Limit: {plan.limit_val}"
+        )
+
+        # 2. SQL Generation
+        logger.info("Stage 2 — SQL Generation")
+        sql_result = self.generate_sql(
+            question=question,
+            schema_info=schema_str,
+            query_plan=plan_text,
+        )
+        sql = self._clean_sql(sql_result.sql_query)
+
+        # 3. Code-based schema validation (instant — no LLM call)
+        logger.info("Stage 3 — Schema Validation")
+        from db.schema import get_schema
+        schema_valid, schema_issues = check_sql_against_schema(sql, get_schema())
+        if not schema_valid:
+            logger.warning(f"Schema issues detected: {schema_issues}")
+            # Try regenerating SQL once with the issues as feedback
+            sql_result = self.generate_sql(
+                question=question,
+                schema_info=schema_str,
+                query_plan=plan_text + f"\n\nPREVIOUS SQL HAD ISSUES: {schema_issues}. Fix them.",
+            )
+            sql = self._clean_sql(sql_result.sql_query)
+
+        # 4. Safety validation (no LLM call)
+        is_safe, reason = validate_sql(sql)
+        if not is_safe:
+            return {
+                "sql": sql,
+                "data": [],
+                "answer": f"Query rejected: {reason}",
+                "insights": "",
+            }
+
+        # 5. SQL Execution + repair loop
+        logger.info("Stage 4 — Executing SQL")
+        exec_result = execute_sql(sql)
+
+        for attempt in range(MAX_REPAIR_RETRIES):
+            if exec_result["success"]:
+                break
+            logger.warning(f"SQL error (attempt {attempt + 1}): {exec_result['error']}")
+            repair_result = self.repair(
+                sql_query=sql,
+                error_message=exec_result["error"],
+                schema_info=schema_str,
+                question=question,
+            )
+            sql = self._clean_sql(repair_result.corrected_sql)
+            is_safe, reason = validate_sql(sql)
+            if not is_safe:
+                return {
+                    "sql": sql,
+                    "data": [],
+                    "answer": f"Repaired query rejected: {reason}",
+                    "insights": "",
+                }
+            exec_result = execute_sql(sql)
+
+        if not exec_result["success"]:
+            return {
+                "sql": sql,
+                "data": [],
+                "answer": f"Failed after {MAX_REPAIR_RETRIES} repairs. Error: {exec_result['error']}",
+                "insights": "",
+            }
+
+        data = exec_result["data"]
+        data_for_llm = data[:50]
+        results_json = json.dumps(data_for_llm, default=str)
+
+        # 6. Interpret & Insight (single LLM call replaces 2 former stages)
+        logger.info("Stage 5 — Interpret & Insight")
+        result = self.interpret(
+            question=question,
+            sql_query=sql,
+            query_results=results_json,
+        )
+
+        return {
+            "sql": sql,
+            "data": data,
+            "answer": result.answer,
+            "insights": result.insights,
+        }
+
+    def generate_sql_only(self, question: str) -> str:
+        """Run the pipeline up to SQL generation and return just the SQL."""
+        schema_str = format_schema()
+        rels_str = format_relationships()
+        profile_str = get_data_profile()
+
+        plan = self.analyze(
+            question=question,
+            schema_info=schema_str,
+            relationships=rels_str,
+            data_profile=profile_str,
+        )
+
+        plan_text = (
+            f"Intent: {plan.intent}\n"
+            f"Tables: {plan.relevant_tables}\n"
+            f"Columns: {plan.relevant_columns}\n"
+            f"Joins: {plan.join_conditions}\n"
+            f"Where: {plan.where_conditions}\n"
+            f"Aggregations: {plan.aggregations}\n"
+            f"Group By: {plan.group_by}\n"
+            f"Order By: {plan.order_by}\n"
+            f"Limit: {plan.limit_val}"
+        )
+
+        sql_result = self.generate_sql(
+            question=question,
+            schema_info=schema_str,
+            query_plan=plan_text,
+        )
+        sql = self._clean_sql(sql_result.sql_query)
+
+        # Code-based schema check
+        from db.schema import get_schema
+        schema_valid, schema_issues = check_sql_against_schema(sql, get_schema())
+        if not schema_valid:
+            sql_result = self.generate_sql(
+                question=question,
+                schema_info=schema_str,
+                query_plan=plan_text + f"\n\nPREVIOUS SQL HAD ISSUES: {schema_issues}. Fix them.",
+            )
+            sql = self._clean_sql(sql_result.sql_query)
+
+        return sql
+
+    # ── helpers ─────────────────────────────────────────────────────────
+
+    @staticmethod
+    def _clean_sql(raw: str) -> str:
+        """Strip markdown fences, trailing prose, and whitespace from LLM SQL."""
+        sql = raw.strip()
+
+        # 1. Remove ```sql ... ``` wrappers
+        if sql.startswith("```"):
+            lines = sql.split("\n")
+            lines = [l for l in lines if not l.strip().startswith("```")]
+            sql = "\n".join(lines).strip()
+
+        # 2. Extract only the first valid SQL statement
+        match = re.search(
+            r"((?:SELECT|WITH)\b[\s\S]*?)(;|\n\n(?=[A-Z][a-z])|$)",
+            sql,
+            re.IGNORECASE,
+        )
+        if match:
+            sql = match.group(1).strip()
+
+        # 3. Remove trailing lines that look like natural language
+        cleaned_lines: list[str] = []
+        for line in sql.split("\n"):
+            stripped = line.strip()
+            if not stripped:
+                cleaned_lines.append(line)
+                continue
+            if re.match(
+                r"^(However|Note|This|The|Please|But|Also|In |It |I |Here|Since|Because|Although|Unfortunately)",
+                stripped,
+            ):
+                break
+            cleaned_lines.append(line)
+
+        sql = "\n".join(cleaned_lines).strip()
+
+        # 4. Remove trailing semicolons
+        sql = sql.rstrip(";")
+
+        return sql

ai/signatures.py

@@ -0,0 +1,136 @@
+"""DSPy Signature definitions — optimized for speed.
+
+Consolidated from 8 signatures down to 4 to minimize LLM round-trips:
+1. AnalyzeAndPlan  (combines question understanding + schema analysis + query planning)
+2. SQLGeneration
+3. SQLSelfCritique + Repair (combined)
+4. InterpretAndInsight (combines result interpretation + insight generation)
+"""
+
+import dspy
+
+
+# ── 1. Analyze & Plan (combines 3 former stages) ───────────────────────────
+
+class AnalyzeAndPlan(dspy.Signature):
+    """You are an expert SQL analyst with strong business intelligence skills.
+    Given a user question, a database schema, and a DATA PROFILE showing actual
+    values in the database, analyze the question and produce a detailed query plan.
+
+    CRITICAL BUSINESS RULES — you MUST follow these:
+    1. When calculating revenue, sales, or monetary metrics, ONLY include
+       records with a completed/closed/successful status. Filter out cancelled,
+       pending, open, returned, or failed records.
+    2. Look at the data profile to see which status/categorical values exist
+       and decide which ones represent VALID/COMPLETED transactions.
+    3. For AOV (Average Order Value), divide total revenue of CLOSED orders
+       by the COUNT of CLOSED orders only.
+    4. When a column like 'status' exists, ALWAYS consider whether filtering
+       by status is needed for accurate business metrics.
+    5. For inventory/stock metrics, consider item states appropriately.
+    6. When computing counts, totals, or averages, think about which records
+       should logically be included vs excluded.
+
+    Steps:
+    1. Understand the user's question (intent, metrics, entities, filters)
+    2. Review the DATA PROFILE to understand actual values in the database
+    3. Identify which tables and columns are relevant
+    4. Determine appropriate filters (especially status-based) for accurate results
+    5. Produce a complete logical query plan"""
+
+    question = dspy.InputField(desc="The user's natural-language question")
+    schema_info = dspy.InputField(desc="Full database schema with table names, columns, and types")
+    relationships = dspy.InputField(desc="Known relationships between tables")
+    data_profile = dspy.InputField(desc="Data profile showing actual values: distinct categorical values, numeric ranges, date ranges")
+
+    intent = dspy.OutputField(desc="What the user wants to know (1 sentence)")
+    relevant_tables = dspy.OutputField(desc="Comma-separated list of tables needed")
+    relevant_columns = dspy.OutputField(desc="Comma-separated list of table.column pairs needed")
+    join_conditions = dspy.OutputField(desc="JOIN conditions to use, or 'none'")
+    where_conditions = dspy.OutputField(desc="WHERE conditions including status/state filters for accurate business metrics, or 'none'")
+    aggregations = dspy.OutputField(desc="Aggregation functions to apply, or 'none'")
+    group_by = dspy.OutputField(desc="GROUP BY columns, or 'none'")
+    order_by = dspy.OutputField(desc="ORDER BY clause, or 'none'")
+    limit_val = dspy.OutputField(desc="LIMIT value, or 'none'")
+
+
+# ── 2. SQL Generation ──────────────────────────────────────────────────────
+
+class SQLGeneration(dspy.Signature):
+    """Generate a valid PostgreSQL SELECT query based on the query plan.
+    The query must be syntactically correct and only reference existing
+    tables and columns from the schema.
+
+    BUSINESS RULES:
+    - Include status/state filters from the query plan for accurate metrics
+    - Use appropriate aggregation functions
+    - Ensure the query respects business logic (e.g., only closed orders for revenue)
+
+    CRITICAL: Output ONLY the raw SQL. No markdown, no explanation, no comments."""
+
+    question = dspy.InputField(desc="The user's question")
+    schema_info = dspy.InputField(desc="Database schema")
+    query_plan = dspy.InputField(desc="Detailed logical query plan")
+
+    sql_query = dspy.OutputField(
+        desc="A valid PostgreSQL SELECT query. Output ONLY the raw SQL code. "
+             "Do NOT include any explanation, comments, markdown, or text before or after the SQL. "
+             "Do NOT wrap in code fences. Just the pure SQL statement."
+    )
+
+
+# ── 3. SQL Self-Critique & Repair (combined) ───────────────────────────────
+
+class SQLCritiqueAndFix(dspy.Signature):
+    """Evaluate a generated SQL query for correctness against the schema.
+    Check that all tables exist, all columns exist, JOINs are valid,
+    GROUP BY matches aggregations, and filters reference real columns.
+    If any issues are found, output the corrected SQL. If valid, repeat the SQL exactly."""
+
+    sql_query = dspy.InputField(desc="The generated SQL query")
+    schema_info = dspy.InputField(desc="Database schema")
+    question = dspy.InputField(desc="The original question")
+
+    is_valid = dspy.OutputField(desc="yes or no")
+    issues = dspy.OutputField(desc="List of issues found, or 'none'")
+    corrected_sql = dspy.OutputField(
+        desc="Corrected SQL query if issues found, otherwise repeat the original SQL exactly. "
+             "Output ONLY raw SQL code with no explanation or text."
+    )
+
+
+# ── 4. Interpret & Insight (combined) ──────────────────────────────────────
+
+class InterpretAndInsight(dspy.Signature):
+    """Interpret SQL query results for a non-technical user and generate insights.
+
+    1. Summarize the main findings in plain English (2-3 sentences)
+    2. Identify patterns, dominant contributors, outliers, and business implications"""
+
+    question = dspy.InputField(desc="The original question")
+    sql_query = dspy.InputField(desc="The SQL query that was executed")
+    query_results = dspy.InputField(desc="The query results as JSON")
+
+    answer = dspy.OutputField(
+        desc="A clear, non-technical explanation of the results (2-3 sentences)"
+    )
+    insights = dspy.OutputField(
+        desc="3-5 bullet-point analytical insights about the data"
+    )
+
+
+# ── 5. SQL Repair (for execution errors) ──────────────────────────────────
+
+class SQLRepair(dspy.Signature):
+    """Given a SQL query that produced a database error, generate a
+    corrected query that avoids the error."""
+
+    sql_query = dspy.InputField(desc="The SQL query that failed")
+    error_message = dspy.InputField(desc="The database error message")
+    schema_info = dspy.InputField(desc="Database schema")
+    question = dspy.InputField(desc="The original user question")
+
+    corrected_sql = dspy.OutputField(
+        desc="A corrected PostgreSQL SELECT query. Output ONLY the raw SQL code. "
+             "Do NOT include any explanation, comments, or text before or after the SQL."
+    )

ai/validator.py

@@ -0,0 +1,83 @@
+"""SQL safety validation.
+
+Rejects any query that is not a pure SELECT statement.
+"""
+
+import re
+
+_FORBIDDEN_KEYWORDS = [
+    r"\bDROP\b",
+    r"\bDELETE\b",
+    r"\bUPDATE\b",
+    r"\bALTER\b",
+    r"\bTRUNCATE\b",
+    r"\bINSERT\b",
+    r"\bCREATE\b",
+    r"\bGRANT\b",
+    r"\bREVOKE\b",
+    r"\bEXEC\b",
+    r"\bEXECUTE\b",
+]
+
+_FORBIDDEN_PATTERN = re.compile("|".join(_FORBIDDEN_KEYWORDS), re.IGNORECASE)
+
+
+def validate_sql(sql: str) -> tuple[bool, str]:
+    """Check if a SQL string is safe to execute.
+
+    Returns
+    -------
+    (is_safe, reason)
+    """
+    stripped = sql.strip().rstrip(";").strip()
+
+    if not stripped:
+        return False, "Empty query."
+
+    # Must start with SELECT or WITH (CTE)
+    if not re.match(r"^\s*(SELECT|WITH)\b", stripped, re.IGNORECASE):
+        return False, "Only SELECT queries are allowed."
+
+    # Check for forbidden keywords
+    match = _FORBIDDEN_PATTERN.search(stripped)
+    if match:
+        return False, f"Forbidden keyword detected: {match.group().upper()}"
+
+    return True, ""
+
+
+def check_sql_against_schema(sql: str, schema: dict[str, list[dict]]) -> tuple[bool, list[str]]:
+    """Programmatically check that tables/columns in SQL exist in the schema.
+
+    Returns (is_valid, list_of_issues).
+    Much faster and more accurate than LLM-based critique.
+    """
+    issues: list[str] = []
+
+    # Build lookup sets
+    all_tables = {t.lower() for t in schema}
+    table_columns: dict[str, set[str]] = {}
+    for t, cols in schema.items():
+        table_columns[t.lower()] = {c["column_name"].lower() for c in cols}
+    all_columns = set()
+    for cols in table_columns.values():
+        all_columns |= cols
+
+    sql_upper = sql.upper()
+
+    # Extract table references (FROM / JOIN)
+    table_refs = re.findall(
+        r'(?:FROM|JOIN)\s+"?(\w+)"?', sql, re.IGNORECASE
+    )
+    for tref in table_refs:
+        if tref.lower() not in all_tables:
+            issues.append(f"Table '{tref}' not found in schema")
+
+    # Basic check: if GROUP BY is present, verify SELECT has aggregation or is in GROUP BY
+    # (lightweight check — not full SQL parsing)
+    if "GROUP BY" in sql_upper and "SELECT" in sql_upper:
+        if not any(fn in sql_upper for fn in ["SUM(", "COUNT(", "AVG(", "MIN(", "MAX("]):
+            issues.append("GROUP BY present but no aggregation function found")
+
+    return (len(issues) == 0, issues)
+

app.py

@@ -0,0 +1,101 @@
+"""FastAPI application — AI SQL Analyst API and frontend server."""
+
+import logging
+from pathlib import Path
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import FileResponse
+from fastapi.staticfiles import StaticFiles
+from pydantic import BaseModel
+
+logging.basicConfig(level=logging.INFO, format="%(asctime)s  %(name)s  %(message)s")
+
+app = FastAPI(title="AI SQL Analyst", version="1.0.0")
+
+# ── CORS ────────────────────────────────────────────────────────────────────
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+# ── Request / Response schemas ──────────────────────────────────────────────
+
+class QuestionRequest(BaseModel):
+    question: str
+    provider: str = "groq"       # "groq" | "openai"
+
+
+class GenerateSQLResponse(BaseModel):
+    sql: str
+
+
+class ChatResponse(BaseModel):
+    sql: str
+    data: list
+    answer: str
+    insights: str
+
+
+# ── Endpoints ───────────────────────────────────────────────────────────────
+
+@app.post("/generate-sql", response_model=GenerateSQLResponse)
+def generate_sql_endpoint(req: QuestionRequest):
+    from ai.pipeline import SQLAnalystPipeline
+
+    pipeline = SQLAnalystPipeline(provider=req.provider)
+    sql = pipeline.generate_sql_only(req.question)
+    return GenerateSQLResponse(sql=sql)
+
+
+@app.post("/chat", response_model=ChatResponse)
+def chat_endpoint(req: QuestionRequest):
+    from ai.pipeline import SQLAnalystPipeline
+
+    pipeline = SQLAnalystPipeline(provider=req.provider)
+    result = pipeline.run(req.question)
+    return ChatResponse(**result)
+
+
+# ── Schema info endpoint (for debugging / transparency) ─────────────────────
+
+@app.get("/schema")
+def schema_endpoint():
+    from db.schema import get_schema
+    return get_schema()
+
+
+@app.get("/relationships")
+def relationships_endpoint():
+    from db.relationships import discover_relationships
+    rels = discover_relationships()
+    return [
+        {
+            "table_a": r.table_a, "column_a": r.column_a,
+            "table_b": r.table_b, "column_b": r.column_b,
+            "confidence": r.confidence, "source": r.source,
+        }
+        for r in rels
+    ]
+
+
+# ── Frontend static files ──────────────────────────────────────────────────
+
+FRONTEND_DIR = Path(__file__).parent / "frontend"
+
+app.mount("/static", StaticFiles(directory=str(FRONTEND_DIR)), name="static")
+
+
+@app.get("/")
+def serve_frontend():
+    return FileResponse(str(FRONTEND_DIR / "index.html"))
+
+
+# ── Run ─────────────────────────────────────────────────────────────────────
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run("app:app", host="0.0.0.0", port=8000, reload=True)

config.py

@@ -0,0 +1,17 @@
+"""Central configuration — reads .env and exposes all settings."""
+
+import os
+from dotenv import load_dotenv
+
+load_dotenv()
+
+# ── Database ────────────────────────────────────────────────────────────────
+DATABASE_URL: str = os.getenv("DATABASE_URL", "postgresql://postgres:universe@localhost:5432/postgres")
+
+# ── Groq ────────────────────────────────────────────────────────────────────
+GROQ_API_KEY: str = os.getenv("GROQ_API_KEY", "")
+GROQ_MODEL: str = os.getenv("GROQ_MODEL", "llama-3.3-70b-versatile")
+
+# ── OpenAI ──────────────────────────────────────────────────────────────────
+OPENAI_API_KEY: str = os.getenv("OPENAI_API_KEY", "")
+OPENAI_MODEL: str = os.getenv("OPENAI_MODEL", "gpt-4o")

data_sync.py

@@ -0,0 +1,100 @@
+"""Excel → PostgreSQL data synchronization script.
+
+Usage:
+    python data_sync.py path/to/file.xlsx
+    python data_sync.py path/to/folder/       (syncs all .xlsx files)
+
+Normalizes column names to lowercase with underscores,
+then upserts each sheet/file into a PostgreSQL table.
+"""
+
+import os
+import re
+import sys
+
+import pandas as pd
+from sqlalchemy import text
+
+from db.connection import get_engine
+
+
+def normalize_column(name: str) -> str:
+    """Lowercase, strip, and replace non-alphanumeric chars with underscore."""
+    name = str(name).strip().lower()
+    name = re.sub(r"[^a-z0-9]+", "_", name)
+    name = name.strip("_")
+    return name or "unnamed_col"
+
+
+def sync_dataframe(df: pd.DataFrame, table_name: str) -> None:
+    """Write a DataFrame to PostgreSQL, replacing the existing table."""
+    engine = get_engine()
+
+    # Normalize columns
+    df.columns = [normalize_column(c) for c in df.columns]
+
+    # Deduplicate column names
+    seen: dict[str, int] = {}
+    new_cols: list[str] = []
+    for col in df.columns:
+        if col in seen:
+            seen[col] += 1
+            new_cols.append(f"{col}_{seen[col]}")
+        else:
+            seen[col] = 0
+            new_cols.append(col)
+    df.columns = new_cols
+
+    df.to_sql(table_name, engine, if_exists="replace", index=False)
+    print(f"  ✓ Table '{table_name}' synced — {len(df)} rows, {len(df.columns)} columns")
+
+
+def sync_excel(filepath: str) -> None:
+    """Sync all sheets in an Excel file to separate tables."""
+    basename = os.path.splitext(os.path.basename(filepath))[0]
+    table_name = normalize_column(basename)
+
+    xls = pd.ExcelFile(filepath)
+    sheets = xls.sheet_names
+
+    if len(sheets) == 1:
+        df = pd.read_excel(filepath, sheet_name=sheets[0])
+        sync_dataframe(df, table_name)
+    else:
+        for sheet in sheets:
+            df = pd.read_excel(filepath, sheet_name=sheet)
+            sheet_table = f"{table_name}_{normalize_column(sheet)}"
+            sync_dataframe(df, sheet_table)
+
+
+def main() -> None:
+    if len(sys.argv) < 2:
+        print("Usage: python data_sync.py <path_to_xlsx_or_folder>")
+        sys.exit(1)
+
+    target = sys.argv[1]
+
+    if os.path.isdir(target):
+        files = [
+            os.path.join(target, f)
+            for f in os.listdir(target)
+            if f.endswith((".xlsx", ".xls"))
+        ]
+        if not files:
+            print(f"No Excel files found in {target}")
+            sys.exit(1)
+        for fp in sorted(files):
+            print(f"Syncing: {fp}")
+            sync_excel(fp)
+    elif os.path.isfile(target):
+        print(f"Syncing: {target}")
+        sync_excel(target)
+    else:
+        print(f"Path not found: {target}")
+        sys.exit(1)
+
+    print("\n✓ Data sync complete.")
+
+
+if __name__ == "__main__":
+    main()

db/__init__.py

@@ -0,0 +1 @@
+# db package

db/connection.py

@@ -0,0 +1,21 @@
+"""SQLAlchemy engine and connection helpers."""
+
+from sqlalchemy import create_engine
+from sqlalchemy.engine import Engine
+
+import config
+
+_engine: Engine | None = None
+
+
+def get_engine() -> Engine:
+    """Return a singleton SQLAlchemy engine."""
+    global _engine
+    if _engine is None:
+        _engine = create_engine(config.DATABASE_URL, pool_pre_ping=True)
+    return _engine
+
+
+def get_connection():
+    """Return a new database connection (context-manager)."""
+    return get_engine().connect()

db/executor.py

@@ -0,0 +1,38 @@
+"""Safe SQL execution against PostgreSQL.
+
+Only SELECT queries are allowed. Results are returned as list[dict].
+Database errors are captured and returned for the AI repair loop.
+"""
+
+from typing import Any
+
+from sqlalchemy import text
+
+from db.connection import get_engine
+from ai.validator import validate_sql
+
+
+def execute_sql(sql: str) -> dict[str, Any]:
+    """Execute a SQL query and return results or error.
+
+    Returns
+    -------
+    dict with keys:
+        success : bool
+        data    : list[dict]   (on success)
+        columns : list[str]    (on success)
+        error   : str          (on failure)
+    """
+    # Safety gate
+    is_safe, reason = validate_sql(sql)
+    if not is_safe:
+        return {"success": False, "data": [], "columns": [], "error": reason}
+
+    try:
+        with get_engine().connect() as conn:
+            result = conn.execute(text(sql))
+            columns = list(result.keys())
+            rows = [dict(zip(columns, row)) for row in result.fetchall()]
+            return {"success": True, "data": rows, "columns": columns, "error": ""}
+    except Exception as exc:
+        return {"success": False, "data": [], "columns": [], "error": str(exc)}

db/profiler.py

@@ -0,0 +1,267 @@
+"""Data profiler — samples the actual database to give the AI business context.
+
+Profiles each table to discover:
+- Categorical columns and their distinct values (status, type, category, etc.)
+- Numeric column ranges (min, max, avg)
+- Date column ranges
+- Sample rows
+
+This info is injected into the AI prompts so it can make smart
+business decisions (e.g., filter by status='closed' for revenue).
+"""
+
+import time
+from typing import Any
+
+from sqlalchemy import text
+
+from db.connection import get_engine
+from db.schema import get_schema
+
+# ── Cache ───────────────────────────────────────────────────────────────────
+_profile_cache: str | None = None
+_profile_ts: float = 0.0
+_PROFILE_TTL: float = 600.0  # 10 minutes
+
+
+def get_data_profile(force_refresh: bool = False) -> str:
+    """Return a formatted data profile string for prompt injection."""
+    global _profile_cache, _profile_ts
+
+    if not force_refresh and _profile_cache and (time.time() - _profile_ts < _PROFILE_TTL):
+        return _profile_cache
+
+    schema = get_schema()
+    profile_parts: list[str] = []
+
+    engine = get_engine()
+    with engine.connect() as conn:
+        for table, columns in schema.items():
+            table_profile = _profile_table(conn, table, columns)
+            if table_profile:
+                profile_parts.append(table_profile)
+
+    # Auto-generate business rules
+    rules = _generate_business_rules(schema)
+    if rules:
+        profile_parts.append(rules)
+
+    _profile_cache = "\n".join(profile_parts)
+    _profile_ts = time.time()
+    return _profile_cache
+
+
+def _profile_table(conn, table: str, columns: list[dict]) -> str:
+    """Profile a single table."""
+    lines: list[str] = [f"TABLE PROFILE: {table}"]
+
+    # Row count
+    try:
+        count = conn.execute(text(f'SELECT count(*) FROM "{table}"')).scalar()
+        lines.append(f"  Total rows: {count}")
+    except Exception:
+        return ""
+
+    if count == 0:
+        lines.append("  (empty table)")
+        return "\n".join(lines)
+
+    # Profile each column
+    for col in columns:
+        cname = col["column_name"]
+        dtype = col["data_type"]
+
+        try:
+            if _is_categorical(dtype, cname):
+                profile = _profile_categorical(conn, table, cname, count)
+                if profile:
+                    lines.append(profile)
+            elif _is_numeric(dtype):
+                profile = _profile_numeric(conn, table, cname)
+                if profile:
+                    lines.append(profile)
+            elif _is_date(dtype):
+                profile = _profile_date(conn, table, cname)
+                if profile:
+                    lines.append(profile)
+        except Exception:
+            continue
+
+    lines.append("")
+    return "\n".join(lines)
+
+
+def _is_categorical(dtype: str, cname: str) -> bool:
+    """Check if a column is likely categorical (status, type, category, etc.)."""
+    categorical_types = {"character varying", "text", "varchar", "char", "character"}
+    categorical_keywords = {
+        "status", "state", "type", "category", "kind", "class",
+        "group", "level", "tier", "grade", "priority", "stage",
+        "flag", "mode", "role", "region", "country", "city",
+        "gender", "channel", "source", "segment", "department",
+    }
+    if dtype.lower() in categorical_types:
+        # Check if the column name suggests it's categorical
+        lower_name = cname.lower()
+        if any(kw in lower_name for kw in categorical_keywords):
+            return True
+        # Also profile short text columns
+        return True
+    return False
+
+
+def _is_numeric(dtype: str) -> bool:
+    numeric_types = {
+        "integer", "bigint", "smallint", "numeric", "real",
+        "double precision", "decimal", "float", "int",
+    }
+    return dtype.lower() in numeric_types
+
+
+def _is_date(dtype: str) -> bool:
+    date_types = {
+        "date", "timestamp", "timestamp without time zone",
+        "timestamp with time zone", "timestamptz",
+    }
+    return dtype.lower() in date_types
+
+
+def _profile_categorical(conn, table: str, col: str, total_rows: int) -> str | None:
+    """Get distinct values for categorical columns (up to 25 values)."""
+    result = conn.execute(text(
+        f'SELECT "{col}", count(*) as cnt FROM "{table}" '
+        f'WHERE "{col}" IS NOT NULL '
+        f'GROUP BY "{col}" ORDER BY cnt DESC LIMIT 25'
+    )).fetchall()
+
+    if not result:
+        return None
+
+    distinct_count = len(result)
+
+    # Only profile if it's truly categorical (not too many unique values)
+    if distinct_count > 20:
+        # Check total distinct count
+        total_distinct = conn.execute(text(
+            f'SELECT count(DISTINCT "{col}") FROM "{table}" WHERE "{col}" IS NOT NULL'
+        )).scalar()
+        if total_distinct > 50:
+            return f"  {col}: {total_distinct} distinct values (high cardinality - not categorical)"
+
+    values_str = ", ".join(
+        f"'{r[0]}' ({r[1]} rows)" for r in result[:15]
+    )
+    return f"  {col}: DISTINCT VALUES = [{values_str}]"
+
+
+def _profile_numeric(conn, table: str, col: str) -> str | None:
+    """Get min, max, avg for numeric columns."""
+    result = conn.execute(text(
+        f'SELECT min("{col}"), max("{col}"), round(avg("{col}")::numeric, 2) '
+        f'FROM "{table}" WHERE "{col}" IS NOT NULL'
+    )).fetchone()
+
+    if not result or result[0] is None:
+        return None
+
+    return f"  {col}: min={result[0]}, max={result[1]}, avg={result[2]}"
+
+
+def _profile_date(conn, table: str, col: str) -> str | None:
+    """Get date range."""
+    result = conn.execute(text(
+        f'SELECT min("{col}"), max("{col}") '
+        f'FROM "{table}" WHERE "{col}" IS NOT NULL'
+    )).fetchone()
+
+    if not result or result[0] is None:
+        return None
+
+    return f"  {col}: from {result[0]} to {result[1]}"
+
+
+def _generate_business_rules(schema: dict[str, list[dict]]) -> str:
+    """Auto-infer business rules from column patterns across all tables."""
+    rules: list[str] = [
+        "=" * 60,
+        "BUSINESS INTELLIGENCE RULES — YOU MUST FOLLOW THESE",
+        "=" * 60,
+    ]
+
+    # ── Rule 0: Query type awareness
+    rules.append("")
+    rules.append("RULE 0 — KNOW YOUR QUERY TYPE:")
+    rules.append("  PRODUCT ATTRIBUTE queries (category, name, weight, details):")
+    rules.append("    → Use product/variant catalog tables directly.")
+    rules.append("    → No status filter needed.")
+    rules.append("  PRODUCT PRICE queries (most expensive, cheapest, price lookup):")
+    rules.append("    → Use sales_order_line_pricing.selling_price_per_unit as source of truth.")
+    rules.append("    → JOIN to product_master for product_name. GROUP BY to avoid duplicates.")
+    rules.append("  TRANSACTIONAL queries (revenue, AOV, order counts, sales trends):")
+    rules.append("    → Use sales tables. MUST filter by sales_order.status = 'closed'.")
+    rules.append("    → Examples: 'total revenue', 'AOV', 'top customers by spending'")
+
+    # ── Rule 1: Avoiding duplicates
+    rules.append("")
+    rules.append("RULE 1 — AVOID DUPLICATE ROWS (CRITICAL):")
+    rules.append("  When JOINing tables, products may have MULTIPLE variants (different karat, quality, etc.).")
+    rules.append("  This causes duplicate product names in results.")
+    rules.append("  ALWAYS use one of these to prevent duplicates:")
+    rules.append("    - GROUP BY product_id (or product_name) with MAX/MIN/AVG on value columns")
+    rules.append("    - SELECT DISTINCT when you only need unique values")
+    rules.append("    - Use subqueries with aggregation before joining")
+    rules.append("  NEVER return raw joins that produce repeated product names.")
+
+    # ── Rule 2: Product price lookup
+    rules.append("")
+    rules.append("RULE 2 — PRODUCT PRICE LOOKUP (SOURCE OF TRUTH):")
+    rules.append("  The SOURCE OF TRUTH for product prices is the sales_order_line_pricing table.")
+    rules.append("  It has 'selling_price_per_unit' which is the actual price per 1 unit of a product.")
+    rules.append("  For 'most expensive products', 'cheapest products', 'product price':")
+    rules.append("    → Query sales_order_line_pricing and JOIN to product tables for product_name")
+    rules.append("    → Use selling_price_per_unit (NOT line_total_price, NOT selling_price from catalog)")
+    rules.append("    → GROUP BY product_id, product_name and use MAX(selling_price_per_unit)")
+    rules.append("    → Join path: sales_order_line_pricing.product_id = product_master.product_id")
+    rules.append("  Do NOT use product_variant_summary.selling_price or variant_sku_table.selling_price")
+    rules.append("  — those are catalog/list prices, not actual transaction prices.")
+    rules.append("  For 'highest revenue products' or 'best selling products':")
+    rules.append("    → Use SUM(line_total_price) grouped by product, filtered by status='closed'")
+
+    # ── Rule 3: Status filtering (only for transactional queries)
+    rules.append("")
+    rules.append("RULE 3 — STATUS FILTERING (TRANSACTIONAL ONLY):")
+    rules.append("  The 'status' column on the sales_order table has values: closed, open, cancelled, processing.")
+    rules.append("  For revenue, AOV, sales counts: WHERE status = 'closed'")
+    rules.append("  For product catalog queries: NO status filter needed")
+    rules.append("  IMPORTANT: The 'status' column is ONLY on the sales_order table.")
+    rules.append("  Do NOT look for payment_status or status on pricing/line tables — it does not exist there.")
+
+    # ── Rule 4: Unit price vs total price
+    rules.append("")
+    rules.append("RULE 4 — UNIT PRICE vs TOTAL PRICE:")
+    rules.append("  line_total_price = selling_price_per_unit × quantity (total for order line)")
+    rules.append("  selling_price_per_unit = the actual price of 1 unit of the product")
+    rules.append("  base_price_per_unit = cost price of 1 unit before margin")
+    rules.append("  NEVER use line_total_price as a product's price — it includes quantity.")
+    rules.append("  To get a product's price: use selling_price_per_unit or selling_price column")
+
+    # ── Rule 5: Common metrics formulas
+    rules.append("")
+    rules.append("RULE 5 — METRIC FORMULAS:")
+    rules.append("  AOV = SUM(so.total_amount) / COUNT(DISTINCT so.so_id) WHERE so.status='closed'")
+    rules.append("  Revenue = SUM(so.total_amount) WHERE so.status='closed'")
+    rules.append("  Most Expensive Product = MAX(pvs.selling_price) GROUP BY product_id, product_name")
+    rules.append("  Margin % = (selling_price - base_price) / selling_price × 100")
+    rules.append("  Order Count = COUNT(DISTINCT so.so_id) WHERE so.status='closed'")
+
+    # ── Rule 6: Table relationships
+    rules.append("")
+    rules.append("RULE 6 — TABLE JOIN PATHS:")
+    rules.append("  Sales chain: sales_order(so_id) → sales_order_line(so_id, sol_id) → sales_order_line_pricing(sol_id)")
+    rules.append("  Product chain: product_master(product_id) → product_variant_summary(product_id) → variant_sku_table(variant_sku)")
+    rules.append("  Sales ↔ Product: sales_order_line.variant_sku = variant_sku_table.variant_sku")
+    rules.append("  Sales ↔ Customer: sales_order.customer_id = customer_master.customer_id")
+    rules.append("  Sales ↔ Payment: sales_order.so_id = sales_order_payments.so_id")
+
+    return "\n".join(rules)
+

db/relationships.py

@@ -0,0 +1,148 @@
+"""Relationship discovery between database tables.
+
+Detects relationships via:
+1. Explicit foreign-key constraints
+2. Matching column names across tables
+3. ID-like suffix patterns (*_id, *_key)
+4. Fuzzy name matching (cust_id ≈ customer_id)
+"""
+
+from dataclasses import dataclass
+from difflib import SequenceMatcher
+
+from sqlalchemy import text
+
+from db.connection import get_engine
+from db.schema import get_schema
+
+
+@dataclass
+class Relationship:
+    table_a: str
+    column_a: str
+    table_b: str
+    column_b: str
+    confidence: float        # 0.0 – 1.0
+    source: str              # "fk", "exact_match", "id_pattern", "fuzzy"
+
+
+def discover_relationships() -> list[Relationship]:
+    """Return all discovered relationships across public tables."""
+    rels: list[Relationship] = []
+    rels.extend(_fk_relationships())
+    rels.extend(_implicit_relationships())
+    return _deduplicate(rels)
+
+
+# ── Explicit FK relationships ───────────────────────────────────────────────
+
+def _fk_relationships() -> list[Relationship]:
+    query = text("""
+        SELECT
+            tc.table_name       AS source_table,
+            kcu.column_name     AS source_column,
+            ccu.table_name      AS target_table,
+            ccu.column_name     AS target_column
+        FROM information_schema.table_constraints tc
+        JOIN information_schema.key_column_usage kcu
+            ON tc.constraint_name = kcu.constraint_name
+            AND tc.table_schema  = kcu.table_schema
+        JOIN information_schema.constraint_column_usage ccu
+            ON ccu.constraint_name = tc.constraint_name
+            AND ccu.table_schema   = tc.table_schema
+        WHERE tc.constraint_type = 'FOREIGN KEY'
+          AND tc.table_schema    = 'public'
+    """)
+
+    rels: list[Relationship] = []
+    with get_engine().connect() as conn:
+        for row in conn.execute(query).fetchall():
+            rels.append(Relationship(
+                table_a=row[0], column_a=row[1],
+                table_b=row[2], column_b=row[3],
+                confidence=1.0, source="fk",
+            ))
+    return rels
+
+
+# ── Implicit relationships ──────────────────────────────────────────────────
+
+def _implicit_relationships() -> list[Relationship]:
+    schema = get_schema()
+    tables = list(schema.keys())
+    rels: list[Relationship] = []
+
+    for i, t1 in enumerate(tables):
+        cols1 = {c["column_name"] for c in schema[t1]}
+        for t2 in tables[i + 1:]:
+            cols2 = {c["column_name"] for c in schema[t2]}
+
+            # 1. Exact column-name matches
+            common = cols1 & cols2
+            for col in common:
+                rels.append(Relationship(
+                    table_a=t1, column_a=col,
+                    table_b=t2, column_b=col,
+                    confidence=0.85, source="exact_match",
+                ))
+
+            # 2. ID-pattern matching  (e.g. "id" in t1 ↔ "t1_id" in t2)
+            for c1 in cols1:
+                if not c1.endswith(("_id", "_key", "id")):
+                    continue
+                for c2 in cols2:
+                    if not c2.endswith(("_id", "_key", "id")):
+                        continue
+                    if c1 == c2:
+                        continue  # already caught above
+                    base1 = c1.rsplit("_", 1)[0] if "_" in c1 else c1
+                    base2 = c2.rsplit("_", 1)[0] if "_" in c2 else c2
+                    if base1 == base2:
+                        rels.append(Relationship(
+                            table_a=t1, column_a=c1,
+                            table_b=t2, column_b=c2,
+                            confidence=0.75, source="id_pattern",
+                        ))
+
+            # 3. Fuzzy matching for remaining column pairs
+            for c1 in cols1:
+                for c2 in cols2:
+                    if c1 == c2:
+                        continue
+                    ratio = SequenceMatcher(None, c1, c2).ratio()
+                    if ratio >= 0.75:
+                        rels.append(Relationship(
+                            table_a=t1, column_a=c1,
+                            table_b=t2, column_b=c2,
+                            confidence=round(ratio * 0.8, 2),
+                            source="fuzzy",
+                        ))
+
+    return rels
+
+
+def _deduplicate(rels: list[Relationship]) -> list[Relationship]:
+    """Keep the highest-confidence relationship for each column pair."""
+    best: dict[tuple, Relationship] = {}
+    for r in rels:
+        key = tuple(sorted([(r.table_a, r.column_a), (r.table_b, r.column_b)]))
+        if key not in best or r.confidence > best[key].confidence:
+            best[key] = r
+    return list(best.values())
+
+
+def format_relationships(rels: list[Relationship] | None = None) -> str:
+    """Format relationships as a readable string for prompt injection."""
+    if rels is None:
+        rels = discover_relationships()
+
+    if not rels:
+        return "No explicit or inferred relationships found between tables."
+
+    lines: list[str] = []
+    for r in sorted(rels, key=lambda x: -x.confidence):
+        lines.append(
+            f"{r.table_a}.{r.column_a} <-> {r.table_b}.{r.column_b}  "
+            f"(confidence: {r.confidence:.0%}, source: {r.source})"
+        )
+    return "\n".join(lines)

db/schema.py

@@ -0,0 +1,75 @@
+"""Database schema introspection via information_schema.
+
+Provides cached access to table/column metadata so the AI pipeline
+always works with the real database structure.
+"""
+
+import time
+from typing import Any
+
+from sqlalchemy import text
+
+from db.connection import get_engine
+
+# ── Cache ───────────────────────────────────────────────────────────────────
+_schema_cache: dict[str, Any] | None = None
+_cache_ts: float = 0.0
+_CACHE_TTL: float = 300.0  # 5 minutes
+
+
+def get_schema(force_refresh: bool = False) -> dict[str, list[dict]]:
+    """Return {table_name: [{column_name, data_type, is_nullable}, …]}.
+
+    Results are cached for 5 minutes.
+    """
+    global _schema_cache, _cache_ts
+
+    if not force_refresh and _schema_cache and (time.time() - _cache_ts < _CACHE_TTL):
+        return _schema_cache
+
+    query = text("""
+        SELECT table_name, column_name, data_type, is_nullable
+        FROM information_schema.columns
+        WHERE table_schema = 'public'
+        ORDER BY table_name, ordinal_position
+    """)
+
+    schema: dict[str, list[dict]] = {}
+    with get_engine().connect() as conn:
+        rows = conn.execute(query).fetchall()
+
+    for row in rows:
+        table = row[0]
+        col_info = {
+            "column_name": row[1],
+            "data_type": row[2],
+            "is_nullable": row[3],
+        }
+        schema.setdefault(table, []).append(col_info)
+
+    _schema_cache = schema
+    _cache_ts = time.time()
+    return schema
+
+
+def format_schema(schema: dict[str, list[dict]] | None = None) -> str:
+    """Format schema as a readable string for prompt injection."""
+    if schema is None:
+        schema = get_schema()
+
+    lines: list[str] = []
+    for table, columns in schema.items():
+        col_strs = []
+        for c in columns:
+            nullable = "NULL" if c["is_nullable"] == "YES" else "NOT NULL"
+            col_strs.append(f"    {c['column_name']}  {c['data_type']}  {nullable}")
+        lines.append(f"TABLE: {table}")
+        lines.extend(col_strs)
+        lines.append("")
+
+    return "\n".join(lines)
+
+
+def get_table_names() -> list[str]:
+    """Return all public table names."""
+    return list(get_schema().keys())

frontend/index.html

@@ -0,0 +1,190 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>AI SQL Analyst — Intelligent Data Explorer</title>
+    <meta name="description" content="Ask natural-language questions about your database and get instant SQL, results, and insights." />
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700;800&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet" />
+    <link rel="stylesheet" href="/static/style.css" />
+</head>
+<body>
+    <!-- ── Background particles ─────────────────────────────────────── -->
+    <div class="bg-effects">
+        <div class="orb orb-1"></div>
+        <div class="orb orb-2"></div>
+        <div class="orb orb-3"></div>
+    </div>
+
+    <div class="container">
+
+        <!-- ── Header ───────────────────────────────────────────────── -->
+        <header class="header">
+            <div class="logo">
+                <div class="logo-icon">
+                    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+                        <path d="M12 2L2 7l10 5 10-5-10-5z"/>
+                        <path d="M2 17l10 5 10-5"/>
+                        <path d="M2 12l10 5 10-5"/>
+                    </svg>
+                </div>
+                <div>
+                    <h1>AI SQL Analyst</h1>
+                    <p class="tagline">Intelligent Data Explorer</p>
+                </div>
+            </div>
+
+            <!-- ── Model Switcher ──────────────────────────────────── -->
+            <div class="model-switcher">
+                <span class="switcher-label">Model</span>
+                <div class="switcher-track" id="modelSwitcher">
+                    <button class="switcher-btn active" data-provider="groq">
+                        <span class="btn-dot"></span>
+                        Groq
+                    </button>
+                    <button class="switcher-btn" data-provider="openai">
+                        <span class="btn-dot"></span>
+                        OpenAI
+                    </button>
+                </div>
+            </div>
+        </header>
+
+        <!-- ── Input Section ────────────────────────────────────────── -->
+        <section class="input-section">
+            <div class="input-card glass">
+                <label for="questionInput" class="input-label">
+                    Ask a question about your data
+                </label>
+                <div class="input-wrapper">
+                    <textarea
+                        id="questionInput"
+                        rows="3"
+                        placeholder="e.g. What are the top 10 customers by total revenue?"
+                        spellcheck="false"
+                    ></textarea>
+                    <button id="submitBtn" class="submit-btn" title="Send question">
+                        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round">
+                            <line x1="22" y1="2" x2="11" y2="13"/>
+                            <polygon points="22 2 15 22 11 13 2 9 22 2"/>
+                        </svg>
+                    </button>
+                </div>
+            </div>
+        </section>
+
+        <!-- ── Loading ──────────────────────────────────────────────── -->
+        <div id="loadingIndicator" class="loading hidden">
+            <div class="loading-content">
+                <div class="spinner"></div>
+                <p class="loading-text">Reasoning about your question…</p>
+                <div class="loading-steps">
+                    <span class="step active">Understanding</span>
+                    <span class="step-arrow">→</span>
+                    <span class="step">Analyzing Schema</span>
+                    <span class="step-arrow">→</span>
+                    <span class="step">Planning Query</span>
+                    <span class="step-arrow">→</span>
+                    <span class="step">Generating SQL</span>
+                    <span class="step-arrow">→</span>
+                    <span class="step">Executing</span>
+                    <span class="step-arrow">→</span>
+                    <span class="step">Interpreting</span>
+                </div>
+            </div>
+        </div>
+
+        <!-- ── Results Section ────────���─────────────────────────────── -->
+        <div id="resultsSection" class="results-section hidden">
+
+            <!-- SQL Card -->
+            <div class="result-card glass" id="sqlCard">
+                <div class="card-header">
+                    <div class="card-icon sql-icon">
+                        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+                            <polyline points="16 18 22 12 16 6"/>
+                            <polyline points="8 6 2 12 8 18"/>
+                        </svg>
+                    </div>
+                    <h2>Generated SQL</h2>
+                    <button class="copy-btn" id="copySqlBtn" title="Copy SQL">
+                        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+                            <rect x="9" y="9" width="13" height="13" rx="2"/>
+                            <path d="M5 15H4a2 2 0 01-2-2V4a2 2 0 012-2h9a2 2 0 012 2v1"/>
+                        </svg>
+                    </button>
+                </div>
+                <pre class="sql-code"><code id="sqlOutput"></code></pre>
+            </div>
+
+            <!-- Data Card -->
+            <div class="result-card glass" id="dataCard">
+                <div class="card-header">
+                    <div class="card-icon data-icon">
+                        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+                            <ellipse cx="12" cy="5" rx="9" ry="3"/>
+                            <path d="M21 12c0 1.66-4 3-9 3s-9-1.34-9-3"/>
+                            <path d="M3 5v14c0 1.66 4 3 9 3s9-1.34 9-3V5"/>
+                        </svg>
+                    </div>
+                    <h2>Query Results</h2>
+                    <span class="row-count" id="rowCount"></span>
+                </div>
+                <div class="table-wrapper" id="tableWrapper">
+                    <!-- Table injected by JS -->
+                </div>
+            </div>
+
+            <!-- Answer Card -->
+            <div class="result-card glass" id="answerCard">
+                <div class="card-header">
+                    <div class="card-icon answer-icon">
+                        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+                            <path d="M21 15a2 2 0 01-2 2H7l-4 4V5a2 2 0 012-2h14a2 2 0 012 2z"/>
+                        </svg>
+                    </div>
+                    <h2>Explanation</h2>
+                </div>
+                <p class="answer-text" id="answerOutput"></p>
+            </div>
+
+            <!-- Insights Card -->
+            <div class="result-card glass" id="insightsCard">
+                <div class="card-header">
+                    <div class="card-icon insights-icon">
+                        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+                            <path d="M12 2a7 7 0 017 7c0 2.38-1.19 4.47-3 5.74V17a1 1 0 01-1 1H9a1 1 0 01-1-1v-2.26C6.19 13.47 5 11.38 5 9a7 7 0 017-7z"/>
+                            <line x1="9" y1="21" x2="15" y2="21"/>
+                        </svg>
+                    </div>
+                    <h2>Insights</h2>
+                </div>
+                <div class="insights-text" id="insightsOutput"></div>
+            </div>
+
+        </div>
+
+        <!-- ── Error ────────────────────────────────────────────────── -->
+        <div id="errorSection" class="error-section hidden">
+            <div class="result-card glass error-card">
+                <div class="card-header">
+                    <div class="card-icon error-icon">
+                        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+                            <circle cx="12" cy="12" r="10"/>
+                            <line x1="15" y1="9" x2="9" y2="15"/>
+                            <line x1="9" y1="9" x2="15" y2="15"/>
+                        </svg>
+                    </div>
+                    <h2>Error</h2>
+                </div>
+                <p class="error-text" id="errorOutput"></p>
+            </div>
+        </div>
+
+    </div>
+
+    <script src="/static/script.js"></script>
+</body>
+</html>

frontend/script.js

@@ -0,0 +1,171 @@
+/* ═══════════════════════════════════════════════════════════════════════════
+   AI SQL Analyst — Frontend Logic
+   ═══════════════════════════════════════════════════════════════════════════ */
+
+(function () {
+    "use strict";
+
+    // ── DOM refs ──────────────────────────────────────────────────────────
+    const questionInput   = document.getElementById("questionInput");
+    const submitBtn       = document.getElementById("submitBtn");
+    const loadingIndicator= document.getElementById("loadingIndicator");
+    const resultsSection  = document.getElementById("resultsSection");
+    const errorSection    = document.getElementById("errorSection");
+
+    const sqlOutput       = document.getElementById("sqlOutput");
+    const tableWrapper    = document.getElementById("tableWrapper");
+    const rowCount        = document.getElementById("rowCount");
+    const answerOutput    = document.getElementById("answerOutput");
+    const insightsOutput  = document.getElementById("insightsOutput");
+    const errorOutput     = document.getElementById("errorOutput");
+    const copySqlBtn      = document.getElementById("copySqlBtn");
+
+    const modelSwitcher   = document.getElementById("modelSwitcher");
+
+    let selectedProvider  = "groq";
+    let loadingStepTimer  = null;
+
+    // ── Model Switcher ───────────────────────────────────────────────────
+    modelSwitcher.addEventListener("click", (e) => {
+        const btn = e.target.closest(".switcher-btn");
+        if (!btn) return;
+        modelSwitcher.querySelectorAll(".switcher-btn").forEach(b => b.classList.remove("active"));
+        btn.classList.add("active");
+        selectedProvider = btn.dataset.provider;
+    });
+
+    // ── Submit ────────────────────────────────────────────────────────────
+    submitBtn.addEventListener("click", handleSubmit);
+    questionInput.addEventListener("keydown", (e) => {
+        if (e.key === "Enter" && !e.shiftKey) {
+            e.preventDefault();
+            handleSubmit();
+        }
+    });
+
+    async function handleSubmit() {
+        const question = questionInput.value.trim();
+        if (!question) return;
+
+        showLoading();
+        hideResults();
+        hideError();
+
+        try {
+            const res = await fetch("/chat", {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({ question, provider: selectedProvider }),
+            });
+
+            if (!res.ok) {
+                const err = await res.json().catch(() => ({ detail: res.statusText }));
+                throw new Error(err.detail || `HTTP ${res.status}`);
+            }
+
+            const data = await res.json();
+            renderResults(data);
+        } catch (err) {
+            showError(err.message || "Something went wrong. Please try again.");
+        } finally {
+            hideLoading();
+        }
+    }
+
+    // ── Render Results ───────────────────────────────────────────────────
+    function renderResults(data) {
+        // SQL
+        sqlOutput.textContent = data.sql || "(no SQL generated)";
+
+        // Data table
+        if (data.data && data.data.length > 0) {
+            rowCount.textContent = `${data.data.length} row${data.data.length !== 1 ? "s" : ""}`;
+            tableWrapper.innerHTML = buildTable(data.data);
+        } else {
+            rowCount.textContent = "0 rows";
+            tableWrapper.innerHTML = '<p style="padding:1rem;color:var(--text-muted);">No data returned.</p>';
+        }
+
+        // Answer
+        answerOutput.textContent = data.answer || "";
+
+        // Insights
+        insightsOutput.textContent = data.insights || "";
+
+        resultsSection.classList.remove("hidden");
+    }
+
+    function buildTable(rows) {
+        if (!rows.length) return "";
+        const cols = Object.keys(rows[0]);
+        // Limit display to 200 rows
+        const displayRows = rows.slice(0, 200);
+        let html = "<table><thead><tr>";
+        cols.forEach(c => { html += `<th>${escapeHtml(c)}</th>`; });
+        html += "</tr></thead><tbody>";
+        displayRows.forEach(row => {
+            html += "<tr>";
+            cols.forEach(c => {
+                const val = row[c];
+                html += `<td>${escapeHtml(val === null ? "NULL" : String(val))}</td>`;
+            });
+            html += "</tr>";
+        });
+        html += "</tbody></table>";
+        if (rows.length > 200) {
+            html += `<p style="padding:0.75rem 1rem;color:var(--text-muted);font-size:0.8rem;">Showing 200 of ${rows.length} rows</p>`;
+        }
+        return html;
+    }
+
+    // ── Copy SQL ─────────────────────────────────────────────────────────
+    copySqlBtn.addEventListener("click", () => {
+        const sql = sqlOutput.textContent;
+        navigator.clipboard.writeText(sql).then(() => {
+            copySqlBtn.style.color = "var(--accent-emerald)";
+            setTimeout(() => { copySqlBtn.style.color = ""; }, 1200);
+        });
+    });
+
+    // ── Loading animation ────────────────────────────────────────────────
+    function showLoading() {
+        loadingIndicator.classList.remove("hidden");
+        submitBtn.disabled = true;
+        animateLoadingSteps();
+    }
+
+    function hideLoading() {
+        loadingIndicator.classList.add("hidden");
+        submitBtn.disabled = false;
+        if (loadingStepTimer) clearInterval(loadingStepTimer);
+    }
+
+    function animateLoadingSteps() {
+        const steps = loadingIndicator.querySelectorAll(".step");
+        let idx = 0;
+        steps.forEach(s => s.classList.remove("active"));
+        if (steps.length) steps[0].classList.add("active");
+
+        loadingStepTimer = setInterval(() => {
+            steps.forEach(s => s.classList.remove("active"));
+            idx = (idx + 1) % steps.length;
+            steps[idx].classList.add("active");
+        }, 2000);
+    }
+
+    // ── Visibility helpers ───────────────────────────────────────────────
+    function hideResults() { resultsSection.classList.add("hidden"); }
+    function hideError()   { errorSection.classList.add("hidden"); }
+
+    function showError(msg) {
+        errorOutput.textContent = msg;
+        errorSection.classList.remove("hidden");
+    }
+
+    // ── Escape HTML ──────────────────────────────────────────────────────
+    function escapeHtml(str) {
+        const div = document.createElement("div");
+        div.appendChild(document.createTextNode(str));
+        return div.innerHTML;
+    }
+})();

frontend/style.css

@@ -0,0 +1,639 @@
+/* ═══════════════════════════════════════════════════════════════════════════
+   AI SQL Analyst — Premium Light-Mode Design System (Green Accent)
+   ═══════════════════════════════════════════════════════════════════════════ */
+
+/* ── Reset & Variables ──────────────────────────────────────────────────── */
+*,
+*::before,
+*::after {
+    margin: 0;
+    padding: 0;
+    box-sizing: border-box;
+}
+
+:root {
+    /* Palette — clean white + green */
+    --bg-primary: #ffffff;
+    --bg-secondary: #f8faf9;
+    --bg-card: rgba(255, 255, 255, 0.85);
+    --bg-card-hover: rgba(255, 255, 255, 0.95);
+    --border-subtle: rgba(16, 185, 129, 0.18);
+    --border-glow: rgba(16, 185, 129, 0.35);
+
+    --text-primary: #1e293b;
+    --text-secondary: #475569;
+    --text-muted: #94a3b8;
+
+    --accent-green: #10b981;
+    --accent-green-dark: #059669;
+    --accent-green-light: #34d399;
+    --accent-emerald: #047857;
+    --accent-teal: #0d9488;
+    --accent-cyan: #06b6d4;
+    --accent-amber: #f59e0b;
+    --accent-rose: #f43f5e;
+
+    --gradient-primary: linear-gradient(135deg, #10b981 0%, #059669 50%, #047857 100%);
+    --gradient-subtle: linear-gradient(135deg, rgba(16, 185, 129, 0.06) 0%, rgba(5, 150, 105, 0.04) 100%);
+
+    /* Typography */
+    --font-sans: 'Inter', -apple-system, BlinkMacSystemFont, sans-serif;
+    --font-mono: 'JetBrains Mono', 'Fira Code', monospace;
+
+    /* Sizes */
+    --radius-sm: 8px;
+    --radius-md: 12px;
+    --radius-lg: 16px;
+    --radius-xl: 24px;
+
+    /* Transitions */
+    --transition-fast: 150ms cubic-bezier(0.4, 0, 0.2, 1);
+    --transition-smooth: 300ms cubic-bezier(0.4, 0, 0.2, 1);
+    --transition-spring: 500ms cubic-bezier(0.34, 1.56, 0.64, 1);
+}
+
+html {
+    font-size: 16px;
+    -webkit-font-smoothing: antialiased;
+    -moz-osx-font-smoothing: grayscale;
+}
+
+body {
+    font-family: var(--font-sans);
+    background: var(--bg-primary);
+    color: var(--text-primary);
+    min-height: 100vh;
+    overflow-x: hidden;
+    position: relative;
+}
+
+/* ── Background Effects ─────────────────────────────────────────────────── */
+
+.bg-effects {
+    position: fixed;
+    inset: 0;
+    pointer-events: none;
+    z-index: 0;
+    overflow: hidden;
+}
+
+.orb {
+    position: absolute;
+    border-radius: 50%;
+    filter: blur(120px);
+    opacity: 0.08;
+    animation: orbFloat 20s ease-in-out infinite;
+}
+
+.orb-1 {
+    width: 600px;
+    height: 600px;
+    background: var(--accent-green);
+    top: -200px;
+    left: -100px;
+    animation-duration: 25s;
+}
+
+.orb-2 {
+    width: 500px;
+    height: 500px;
+    background: var(--accent-teal);
+    top: 50%;
+    right: -150px;
+    animation-duration: 30s;
+    animation-delay: -5s;
+}
+
+.orb-3 {
+    width: 400px;
+    height: 400px;
+    background: var(--accent-green-light);
+    bottom: -100px;
+    left: 30%;
+    animation-duration: 22s;
+    animation-delay: -10s;
+}
+
+@keyframes orbFloat {
+    0%, 100% { transform: translate(0, 0) scale(1); }
+    25%      { transform: translate(40px, -30px) scale(1.05); }
+    50%      { transform: translate(-20px, 40px) scale(0.95); }
+    75%      { transform: translate(30px, 20px) scale(1.02); }
+}
+
+/* ── Container ──────────────────────────────────────────────────────────── */
+
+.container {
+    position: relative;
+    z-index: 1;
+    max-width: 1100px;
+    margin: 0 auto;
+    padding: 2rem 1.5rem 4rem;
+}
+
+/* ── Glass Card Base ────────────────────────────────────────────────────── */
+
+.glass {
+    background: var(--bg-card);
+    backdrop-filter: blur(20px);
+    -webkit-backdrop-filter: blur(20px);
+    border: 1px solid var(--border-subtle);
+    border-radius: var(--radius-lg);
+    box-shadow: 0 1px 3px rgba(0, 0, 0, 0.04), 0 4px 12px rgba(16, 185, 129, 0.04);
+    transition: border-color var(--transition-smooth), box-shadow var(--transition-smooth);
+}
+
+.glass:hover {
+    border-color: var(--border-glow);
+    box-shadow: 0 2px 8px rgba(0, 0, 0, 0.05), 0 8px 24px rgba(16, 185, 129, 0.08);
+}
+
+/* ── Header ─────────────────────────────────────────────────────────────── */
+
+.header {
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+    margin-bottom: 2.5rem;
+    flex-wrap: wrap;
+    gap: 1rem;
+}
+
+.logo {
+    display: flex;
+    align-items: center;
+    gap: 1rem;
+}
+
+.logo-icon {
+    width: 48px;
+    height: 48px;
+    background: var(--gradient-primary);
+    border-radius: var(--radius-md);
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    color: white;
+    box-shadow: 0 4px 16px rgba(16, 185, 129, 0.3);
+}
+
+.logo-icon svg {
+    width: 26px;
+    height: 26px;
+}
+
+.header h1 {
+    font-size: 1.6rem;
+    font-weight: 800;
+    background: var(--gradient-primary);
+    -webkit-background-clip: text;
+    -webkit-text-fill-color: transparent;
+    background-clip: text;
+    letter-spacing: -0.02em;
+}
+
+.tagline {
+    font-size: 0.8rem;
+    color: var(--text-muted);
+    font-weight: 400;
+    letter-spacing: 0.04em;
+    text-transform: uppercase;
+}
+
+/* ── Model Switcher ─────────────────────────────────────────────────────── */
+
+.model-switcher {
+    display: flex;
+    align-items: center;
+    gap: 0.75rem;
+}
+
+.switcher-label {
+    font-size: 0.75rem;
+    color: var(--text-muted);
+    text-transform: uppercase;
+    letter-spacing: 0.08em;
+    font-weight: 600;
+}
+
+.switcher-track {
+    display: flex;
+    background: var(--bg-secondary);
+    border: 1px solid var(--border-subtle);
+    border-radius: var(--radius-xl);
+    padding: 3px;
+    gap: 2px;
+}
+
+.switcher-btn {
+    display: flex;
+    align-items: center;
+    gap: 0.4rem;
+    padding: 0.45rem 1rem;
+    border: none;
+    border-radius: var(--radius-xl);
+    background: transparent;
+    color: var(--text-muted);
+    font-family: var(--font-sans);
+    font-size: 0.8rem;
+    font-weight: 500;
+    cursor: pointer;
+    transition: all var(--transition-fast);
+}
+
+.switcher-btn:hover {
+    color: var(--text-secondary);
+}
+
+.switcher-btn.active {
+    background: var(--gradient-primary);
+    color: white;
+    box-shadow: 0 2px 10px rgba(16, 185, 129, 0.3);
+}
+
+.btn-dot {
+    width: 6px;
+    height: 6px;
+    border-radius: 50%;
+    background: currentColor;
+    opacity: 0.6;
+}
+
+.switcher-btn.active .btn-dot {
+    background: #a7f3d0;
+    opacity: 1;
+    box-shadow: 0 0 6px #a7f3d0;
+    animation: dotPulse 2s ease-in-out infinite;
+}
+
+@keyframes dotPulse {
+    0%, 100% { box-shadow: 0 0 4px #a7f3d0; }
+    50%      { box-shadow: 0 0 12px #a7f3d0; }
+}
+
+/* ── Input Section ──────────────────────────────────────────────────────── */
+
+.input-section {
+    margin-bottom: 2rem;
+}
+
+.input-card {
+    padding: 1.5rem;
+}
+
+.input-label {
+    display: block;
+    font-size: 0.85rem;
+    font-weight: 600;
+    color: var(--text-secondary);
+    margin-bottom: 0.75rem;
+    letter-spacing: 0.02em;
+}
+
+.input-wrapper {
+    display: flex;
+    gap: 0.75rem;
+    align-items: flex-end;
+}
+
+textarea {
+    flex: 1;
+    resize: vertical;
+    min-height: 70px;
+    max-height: 200px;
+    padding: 1rem 1.25rem;
+    background: var(--bg-secondary);
+    border: 1px solid var(--border-subtle);
+    border-radius: var(--radius-md);
+    color: var(--text-primary);
+    font-family: var(--font-sans);
+    font-size: 0.95rem;
+    line-height: 1.6;
+    transition: border-color var(--transition-fast), box-shadow var(--transition-fast);
+}
+
+textarea::placeholder {
+    color: var(--text-muted);
+}
+
+textarea:focus {
+    outline: none;
+    border-color: var(--accent-green);
+    box-shadow: 0 0 0 3px rgba(16, 185, 129, 0.15);
+}
+
+.submit-btn {
+    width: 52px;
+    height: 52px;
+    flex-shrink: 0;
+    border: none;
+    border-radius: var(--radius-md);
+    background: var(--gradient-primary);
+    color: white;
+    cursor: pointer;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    transition: transform var(--transition-fast), box-shadow var(--transition-fast);
+    box-shadow: 0 4px 15px rgba(16, 185, 129, 0.3);
+}
+
+.submit-btn:hover {
+    transform: translateY(-2px);
+    box-shadow: 0 6px 25px rgba(16, 185, 129, 0.4);
+}
+
+.submit-btn:active {
+    transform: translateY(0);
+}
+
+.submit-btn svg {
+    width: 22px;
+    height: 22px;
+}
+
+.submit-btn:disabled {
+    opacity: 0.5;
+    cursor: not-allowed;
+    transform: none;
+}
+
+/* ── Loading ────────────────────────────────────────────────────────────── */
+
+.loading {
+    text-align: center;
+    padding: 3rem 1rem;
+}
+
+.loading-content {
+    display: inline-flex;
+    flex-direction: column;
+    align-items: center;
+    gap: 1.25rem;
+}
+
+.spinner {
+    width: 48px;
+    height: 48px;
+    border: 3px solid rgba(16, 185, 129, 0.15);
+    border-top-color: var(--accent-green);
+    border-right-color: var(--accent-green-dark);
+    border-radius: 50%;
+    animation: spin 0.8s linear infinite;
+}
+
+@keyframes spin {
+    to { transform: rotate(360deg); }
+}
+
+.loading-text {
+    font-size: 1rem;
+    font-weight: 500;
+    color: var(--text-secondary);
+}
+
+.loading-steps {
+    display: flex;
+    align-items: center;
+    gap: 0.35rem;
+    flex-wrap: wrap;
+    justify-content: center;
+}
+
+.loading-steps .step {
+    font-size: 0.7rem;
+    padding: 0.25rem 0.5rem;
+    border-radius: var(--radius-sm);
+    background: rgba(16, 185, 129, 0.06);
+    color: var(--text-muted);
+    font-weight: 500;
+    transition: all var(--transition-smooth);
+}
+
+.loading-steps .step.active {
+    background: rgba(16, 185, 129, 0.15);
+    color: var(--accent-green-dark);
+}
+
+.loading-steps .step-arrow {
+    color: var(--text-muted);
+    font-size: 0.65rem;
+    opacity: 0.4;
+}
+
+/* ── Results Section ────────────────────────────────────────────────────── */
+
+.results-section {
+    display: flex;
+    flex-direction: column;
+    gap: 1.25rem;
+    animation: fadeInUp 0.5s ease;
+}
+
+@keyframes fadeInUp {
+    from { opacity: 0; transform: translateY(20px); }
+    to   { opacity: 1; transform: translateY(0); }
+}
+
+.result-card {
+    padding: 1.5rem;
+}
+
+.card-header {
+    display: flex;
+    align-items: center;
+    gap: 0.75rem;
+    margin-bottom: 1rem;
+}
+
+.card-icon {
+    width: 36px;
+    height: 36px;
+    border-radius: var(--radius-sm);
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    flex-shrink: 0;
+}
+
+.card-icon svg {
+    width: 18px;
+    height: 18px;
+}
+
+.sql-icon     { background: rgba(16, 185, 129, 0.1); color: var(--accent-green-dark); }
+.data-icon    { background: rgba(6, 182, 212, 0.1);  color: var(--accent-teal); }
+.answer-icon  { background: rgba(16, 185, 129, 0.1); color: var(--accent-green); }
+.insights-icon{ background: rgba(245, 158, 11, 0.1); color: var(--accent-amber); }
+.error-icon   { background: rgba(244, 63, 94, 0.1);  color: var(--accent-rose); }
+
+.card-header h2 {
+    font-size: 0.95rem;
+    font-weight: 700;
+    color: var(--text-primary);
+    flex: 1;
+    letter-spacing: -0.01em;
+}
+
+.copy-btn {
+    width: 34px;
+    height: 34px;
+    border: 1px solid var(--border-subtle);
+    background: transparent;
+    border-radius: var(--radius-sm);
+    color: var(--text-muted);
+    cursor: pointer;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    transition: all var(--transition-fast);
+}
+
+.copy-btn svg {
+    width: 16px;
+    height: 16px;
+}
+
+.copy-btn:hover {
+    border-color: var(--accent-green);
+    color: var(--accent-green);
+    background: rgba(16, 185, 129, 0.06);
+}
+
+.row-count {
+    font-size: 0.75rem;
+    color: var(--accent-green-dark);
+    padding: 0.2rem 0.6rem;
+    background: rgba(16, 185, 129, 0.08);
+    border-radius: var(--radius-xl);
+    font-weight: 500;
+}
+
+/* ── SQL Code Block ─────────────────────────────────────────────────────── */
+
+.sql-code {
+    background: #f0fdf4;
+    border: 1px solid rgba(16, 185, 129, 0.15);
+    border-radius: var(--radius-md);
+    padding: 1.25rem;
+    overflow-x: auto;
+    font-family: var(--font-mono);
+    font-size: 0.85rem;
+    line-height: 1.7;
+    color: var(--accent-emerald);
+    tab-size: 2;
+}
+
+/* ── Data Table ─────────────────────────────────────────────────────────── */
+
+.table-wrapper {
+    overflow-x: auto;
+    border: 1px solid var(--border-subtle);
+    border-radius: var(--radius-md);
+    max-height: 500px;
+    overflow-y: auto;
+}
+
+table {
+    width: 100%;
+    border-collapse: collapse;
+    font-size: 0.85rem;
+}
+
+thead {
+    position: sticky;
+    top: 0;
+    z-index: 2;
+}
+
+th {
+    background: rgba(16, 185, 129, 0.08);
+    color: var(--accent-green-dark);
+    font-weight: 600;
+    text-transform: uppercase;
+    font-size: 0.7rem;
+    letter-spacing: 0.06em;
+    padding: 0.75rem 1rem;
+    text-align: left;
+    white-space: nowrap;
+    border-bottom: 1px solid var(--border-subtle);
+}
+
+td {
+    padding: 0.65rem 1rem;
+    border-bottom: 1px solid rgba(0, 0, 0, 0.04);
+    color: var(--text-secondary);
+    white-space: nowrap;
+}
+
+tr:hover td {
+    background: rgba(16, 185, 129, 0.03);
+    color: var(--text-primary);
+}
+
+/* ── Answer & Insights ──────────────────────────────────────────────────── */
+
+.answer-text {
+    font-size: 0.95rem;
+    line-height: 1.75;
+    color: var(--text-secondary);
+}
+
+.insights-text {
+    font-size: 0.9rem;
+    line-height: 1.75;
+    color: var(--text-secondary);
+    white-space: pre-wrap;
+}
+
+/* ── Error ──────────────────────────────────────────────────────────────── */
+
+.error-card {
+    border-color: rgba(244, 63, 94, 0.25) !important;
+}
+
+.error-text {
+    font-size: 0.9rem;
+    line-height: 1.7;
+    color: var(--accent-rose);
+}
+
+/* ── Utilities ──────────────────────────────────────────────────────────── */
+
+.hidden {
+    display: none !important;
+}
+
+/* ── Responsive ─────────────────────────────────────────────────────────── */
+
+@media (max-width: 640px) {
+    .container {
+        padding: 1rem;
+    }
+
+    .header {
+        flex-direction: column;
+        align-items: flex-start;
+    }
+
+    .header h1 {
+        font-size: 1.3rem;
+    }
+
+    .input-wrapper {
+        flex-direction: column;
+    }
+
+    .submit-btn {
+        width: 100%;
+        height: 48px;
+    }
+
+    .loading-steps {
+        gap: 0.2rem;
+    }
+
+    .loading-steps .step-arrow {
+        display: none;
+    }
+}

requirements.txt

@@ -0,0 +1,12 @@
+fastapi
+uvicorn
+sqlalchemy
+psycopg2-binary
+dspy
+litellm
+groq
+openai
+pandas
+openpyxl
+pydantic
+python-dotenv

space.yaml

@@ -0,0 +1,4 @@
+sdk: docker
+app_port: 7860
+license: mit
+title: AI SQL Analyst (sqlbot)