Upload folder using huggingface_hub

.dockerignore

@@ -0,0 +1,10 @@
+# Never ship secrets, local logs, or downloaded binaries
+.env
+logs/
+tools/
+__pycache__/
+*.pyc
+.venv/
+venv/
+docs/*.png
+.git/

.env.example

@@ -0,0 +1,29 @@
+# --- Database (SQL Server) ---
+DB_SERVER=162.246.19.13
+DB_PORT=1433
+DB_NAME=IAmInterviewed_QA
+DB_USER=iaiuser_qa
+DB_PASSWORD=your_password_here
+DB_DRIVER=ODBC Driver 18 for SQL Server
+
+# --- LLM backend (OpenAI-compatible) — default: Groq free tier ---
+# Get a free key at https://console.groq.com/keys
+# Works with any OpenAI-compatible endpoint (Groq, ngrok AI Gateway, OpenAI, ...).
+LLM_BASE_URL=https://api.groq.com/openai/v1
+LLM_API_KEY=your_groq_key_here
+LLM_MODEL=llama-3.3-70b-versatile
+# Price per 1M tokens for the projected-cost metric
+LLM_PRICE_IN=0.59
+LLM_PRICE_OUT=0.79
+
+# --- Monitoring --- set a token to protect /api/metrics (empty = open)
+METRICS_TOKEN=
+
+# --- Bot behaviour ---
+# Max rows returned to the model from any single query
+MAX_RESULT_ROWS=200
+# Per-query timeout in seconds
+QUERY_TIMEOUT=30
+# Web origins allowed to embed/call the bot. "*" = any (dev only).
+# In production set to your site: https://www.antern.com,https://antern.com
+ALLOWED_ORIGINS=*

.gitignore

@@ -0,0 +1,7 @@
+.env
+__pycache__/
+*.pyc
+.venv/
+venv/
+logs/
+tools/

Dockerfile

@@ -0,0 +1,29 @@
+# Antern Bot — Hugging Face Spaces (Docker) deployment
+FROM python:3.11-slim
+
+# Microsoft ODBC Driver 18 for SQL Server (needed by pyodbc)
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        curl gnupg2 ca-certificates apt-transport-https unixodbc \
+ && curl -fsSL https://packages.microsoft.com/keys/microsoft.asc \
+        | gpg --dearmor -o /usr/share/keyrings/microsoft-prod.gpg \
+ && echo "deb [arch=amd64,arm64,armhf signed-by=/usr/share/keyrings/microsoft-prod.gpg] https://packages.microsoft.com/debian/12/prod bookworm main" \
+        > /etc/apt/sources.list.d/mssql-release.list \
+ && apt-get update \
+ && ACCEPT_EULA=Y apt-get install -y --no-install-recommends msodbcsql18 \
+ && apt-get clean && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+# Writable log dir regardless of the runtime user
+RUN mkdir -p /app/logs && chmod 777 /app/logs
+
+# Hugging Face Spaces serves on port 7860
+ENV PORT=7860
+EXPOSE 7860
+
+CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "7860"]

agent.py

@@ -0,0 +1,303 @@
+"""Antern Bot — natural-language-to-SQL agent over the IAmInterviewed_QA DB.
+
+Talks to any OpenAI-compatible LLM endpoint (Groq, ngrok AI Gateway, OpenAI,
+self-hosted, ...) in a manual tool-calling loop:
+  user question -> model writes T-SQL -> we run it READ-ONLY -> model explains.
+
+The schema is placed in the system instruction so the model knows the tables,
+columns, and joins available. Two tools are exposed: `run_sql` (run a read-only
+query) and `present` (choose how to display the result: table / chart).
+"""
+from __future__ import annotations
+
+import json
+
+from openai import OpenAI
+
+import config
+import db
+
+# How many result rows to show the MODEL (the full set still goes to the
+# frontend). Keeps the prompt small and cheap.
+MODEL_ROW_PREVIEW = 12
+MAX_TOOL_ITERATIONS = 8
+
+RUN_SQL_TOOL = {
+    "type": "function",
+    "function": {
+        "name": "run_sql",
+        "description": (
+            "Run a single READ-ONLY T-SQL SELECT query against the "
+            "IAmInterviewed_QA SQL Server database and return the rows. Only "
+            "SELECT / WITH queries are permitted. Use this whenever you need "
+            "data to answer the user."
+        ),
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "query": {
+                    "type": "string",
+                    "description": "A single T-SQL SELECT statement. Use TOP "
+                    "(not LIMIT) to cap rows. Do not end with a semicolon.",
+                }
+            },
+            "required": ["query"],
+        },
+    },
+}
+
+PRESENT_TOOL = {
+    "type": "function",
+    "function": {
+        "name": "present",
+        "description": (
+            "Choose how the MOST RECENT run_sql result is displayed. Call this "
+            "AFTER run_sql once you have the data. Use 'table' for multi-row "
+            "results, a chart ('bar', 'line', 'pie') to visualize an "
+            "aggregation, or 'text' for a single value / simple answer."
+        ),
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "format": {
+                    "type": "string",
+                    "enum": ["text", "table", "bar", "line", "pie"],
+                    "description": "How to render the latest result.",
+                },
+                "title": {
+                    "type": "string",
+                    "description": "Short title/caption for the table or chart.",
+                },
+                "x_field": {
+                    "type": "string",
+                    "description": "For charts: column name for the category / "
+                    "x-axis (also the pie slice labels).",
+                },
+                "y_fields": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "description": "For charts: one or more numeric column names "
+                    "to plot on the y-axis (pie uses the first).",
+                },
+            },
+            "required": ["format"],
+        },
+    },
+}
+
+SYSTEM_INTRO = """You are "Antern Bot", a helpful data assistant for the Antern \
+recruitment / interview platform. You answer questions about the data in the \
+IAmInterviewed_QA database (Microsoft SQL Server 2019).
+
+How you work:
+- When a question needs data, call the `run_sql` tool with a single T-SQL SELECT \
+query, read the rows, then answer in clear natural language.
+- This is SQL Server / T-SQL. Use `TOP n` (never `LIMIT`), `OFFSET ... FETCH` for \
+paging, `GETDATE()` for the current time, and square brackets for reserved names.
+- Use ONLY tables and columns that appear in the schema below. Do not guess table \
+names, and give every table an alias and reference columns by that alias. Watch \
+column types when joining (an int id only joins to an int id).
+- You have READ-ONLY access. Never attempt INSERT/UPDATE/DELETE/DDL.
+- Most tables use soft deletes: rows have IsActive (bit) and DeletedDate. Unless \
+the user asks otherwise, filter to active rows (IsActive = 1) for "live" counts.
+- Keep result sets small: aggregate (COUNT, SUM, GROUP BY) or use TOP for examples.
+- If a query fails, READ the error and fix the query — do not repeat the same \
+failing query.
+- Explain results conversationally. Never invent data that isn't in the results.
+- After you have the data, call the `present` tool to choose how it is shown: \
+`table` for multi-row results, `bar`/`line`/`pie` to visualize an aggregation \
+(pass x_field and y_fields as exact column names from your query), or `text` for a \
+single value. For charts, aggregate in SQL first (GROUP BY / TOP n). When you show \
+a table or chart, keep your written answer short — the visual carries the detail.
+
+Note: every table also has standard audit columns not listed below — \
+CreatedDate, ModifiedDate, DeletedDate (datetimeoffset) — in addition to the \
+IsActive (bit) column shown.
+
+Below is the database schema (each table with its meaningful columns, and the \
+foreign-key relationships you can join on):
+"""
+
+# Minimal system prompt for the final "summarise the results" call — the schema
+# isn't needed there, so we drop it to save tokens.
+FINALIZE_SYSTEM = (
+    "You are Antern Bot. The user's question and the SQL query results are in the "
+    "conversation above. Write a clear, concise, friendly answer based only on "
+    "those results. If a table or chart is being shown, keep your text short."
+)
+
+
+class AnternBot:
+    def __init__(self) -> None:
+        if not config.LLM_API_KEY:
+            raise RuntimeError(
+                "LLM_API_KEY is not set. Add it to your .env file. "
+                "For the default Groq backend, get a free key at "
+                "https://console.groq.com/keys"
+            )
+        self.model = config.LLM_MODEL
+        self.client = OpenAI(
+            base_url=config.LLM_BASE_URL, api_key=config.LLM_API_KEY, timeout=60
+        )
+        # Introspect once; the schema goes into the system instruction.
+        self.schema = db.introspect_schema()
+        self.system_instruction = SYSTEM_INTRO + "\n" + self.schema
+        self.tools = [RUN_SQL_TOOL, PRESENT_TOOL]
+
+    @staticmethod
+    def _run_sql(sql: str) -> tuple:
+        """Execute a query. Returns (record_for_ui, model_response, full_result).
+        The model gets only a row preview; the full result is for the frontend."""
+        record: dict = {"query": sql}
+        try:
+            result = db.run_query(sql)
+            record["row_count"] = result["row_count"]
+            record["truncated"] = result["truncated"]
+            preview = result["rows"][:MODEL_ROW_PREVIEW]
+            model_view = {
+                "columns": result["columns"],
+                "rows": preview,
+                "row_count": result["row_count"],
+                "preview_truncated": len(result["rows"]) > len(preview),
+            }
+            return record, {"result": model_view}, result
+        except db.UnsafeQueryError as exc:
+            record["error"] = f"Blocked: {exc}"
+            return record, {"error": f"Query rejected by safety guard: {exc}"}, None
+        except Exception as exc:  # SQL error, connection, etc.
+            record["error"] = str(exc)
+            return record, {"error": f"Query failed: {exc}"}, None
+
+    @staticmethod
+    def _present(args: dict, last_result) -> tuple:
+        """Build a presentation directive paired with the most recent result."""
+        fmt = (args.get("format") or "text").lower()
+        if fmt == "text" or not last_result or not last_result.get("rows"):
+            return None, {"status": "shown as text"}
+        presentation = {
+            "format": fmt,
+            "title": args.get("title"),
+            "x_field": args.get("x_field"),
+            "y_fields": list(args.get("y_fields") or []),
+            "columns": last_result["columns"],
+            "rows": last_result["rows"],
+            "truncated": last_result.get("truncated", False),
+        }
+        return presentation, {"status": f"shown as {fmt}"}
+
+    def chat(self, history: list, user_message: str) -> dict:
+        """Run one user turn through the tool-calling loop.
+
+        `history` is the prior list of clean {role, content} text turns. Returns
+        {answer, queries, presentation, messages}.
+        """
+        messages = [{"role": "system", "content": self.system_instruction}]
+        messages.extend(history)
+        messages.append({"role": "user", "content": user_message})
+
+        queries: list[dict] = []
+        presentation = None
+        last_result = None
+        presented = False
+        answer = ""
+        usage = {"prompt": 0, "completion": 0, "total": 0}
+        llm_calls = 0
+
+        for _ in range(MAX_TOOL_ITERATIONS):
+            if presented:
+                # Finalize call: just summarise the results — schema not needed,
+                # so swap in the minimal system prompt to save tokens.
+                call_messages = [
+                    {"role": "system", "content": FINALIZE_SYSTEM}
+                ] + messages[1:]
+                kwargs = dict(model=self.model, messages=call_messages, temperature=0)
+            else:
+                kwargs = dict(
+                    model=self.model, messages=messages, temperature=0,
+                    tools=self.tools,
+                )
+            resp = self.client.chat.completions.create(**kwargs)
+            llm_calls += 1
+            u = getattr(resp, "usage", None)
+            if u:
+                usage["prompt"] += getattr(u, "prompt_tokens", 0) or 0
+                usage["completion"] += getattr(u, "completion_tokens", 0) or 0
+                usage["total"] += getattr(u, "total_tokens", 0) or 0
+            msg = resp.choices[0].message
+            content = (msg.content or "").strip()
+            tool_calls = msg.tool_calls or []
+            print(
+                f"[antern] turn calls={[tc.function.name for tc in tool_calls]} "
+                f"text={'yes' if content else 'no'}",
+                flush=True,
+            )
+
+            # Echo the assistant turn back into the conversation.
+            assistant_msg = {"role": "assistant", "content": msg.content or ""}
+            if tool_calls:
+                assistant_msg["tool_calls"] = [
+                    {
+                        "id": tc.id,
+                        "type": "function",
+                        "function": {
+                            "name": tc.function.name,
+                            "arguments": tc.function.arguments,
+                        },
+                    }
+                    for tc in tool_calls
+                ]
+            messages.append(assistant_msg)
+
+            if content:
+                answer = content
+            if not tool_calls:
+                break
+
+            # run_sql calls first (so a 'present' in the same batch uses fresh data).
+            sql_calls = [tc for tc in tool_calls if tc.function.name == "run_sql"]
+            other_calls = [tc for tc in tool_calls if tc.function.name != "run_sql"]
+            for tc in sql_calls:
+                args = self._args(tc)
+                record, model_response, full = self._run_sql(args.get("query", ""))
+                if full is not None:
+                    last_result = full
+                if record.get("error"):
+                    print(f"[antern] sql error: {record['error']} | sql={record['query'][:200]}", flush=True)
+                queries.append(record)
+                messages.append({"role": "tool", "tool_call_id": tc.id,
+                                 "content": json.dumps(model_response, default=str)})
+            for tc in other_calls:
+                if tc.function.name == "present":
+                    presentation, model_response = self._present(self._args(tc), last_result)
+                    presented = True
+                else:
+                    model_response = {"error": f"Unknown tool: {tc.function.name}"}
+                messages.append({"role": "tool", "tool_call_id": tc.id,
+                                 "content": json.dumps(model_response, default=str)})
+
+        if not answer:
+            answer = (
+                "I found the data but had trouble summarising it. Please try "
+                "rephrasing or narrowing your question."
+            )
+
+        new_history = list(history)
+        new_history.append({"role": "user", "content": user_message})
+        new_history.append({"role": "assistant", "content": answer})
+
+        return {
+            "answer": answer,
+            "queries": queries,
+            "presentation": presentation,
+            "messages": new_history,
+            "usage": usage,
+            "llm_calls": llm_calls,
+        }
+
+    @staticmethod
+    def _args(tool_call) -> dict:
+        """Parse a tool call's JSON-string arguments into a dict."""
+        try:
+            return json.loads(tool_call.function.arguments or "{}")
+        except Exception:
+            return {}

app.py

@@ -0,0 +1,172 @@
+"""FastAPI web app for Antern Bot: serves a chat UI and a /api/chat endpoint."""
+from __future__ import annotations
+
+import time
+import uuid
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI, Header
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import FileResponse, JSONResponse
+from fastapi.staticfiles import StaticFiles
+from pydantic import BaseModel
+from pathlib import Path
+
+import config
+import monitoring
+from agent import AnternBot
+
+STATIC_DIR = Path(__file__).parent / "static"
+
+# In-memory conversation store: session_id -> list of API message dicts.
+# Fine for a single-process app; swap for Redis/DB if you scale out.
+SESSIONS: dict[str, list[dict]] = {}
+MAX_HISTORY_MESSAGES = 24  # cap stored turns to bound token growth
+
+bot: AnternBot | None = None
+INIT_ERROR: str | None = None
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    global bot, INIT_ERROR
+    try:
+        bot = AnternBot()  # introspects schema + checks API key at startup
+        monitoring.log_event("startup", status="ready", model=bot.model)
+    except Exception as exc:  # missing API key, DB unreachable, etc.
+        INIT_ERROR = str(exc)
+        monitoring.log_event("startup", status="failed", error=str(exc))
+    yield
+
+
+app = FastAPI(title="Antern Bot", lifespan=lifespan)
+
+# Allow the widget to call the API from other web pages (configurable origins).
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=config.ALLOWED_ORIGINS,
+    allow_methods=["GET", "POST"],
+    allow_headers=["*"],
+)
+
+
+class ChatRequest(BaseModel):
+    message: str
+    session_id: str | None = None
+
+
+class ResetRequest(BaseModel):
+    session_id: str
+
+
+@app.get("/")
+def index() -> FileResponse:
+    return FileResponse(STATIC_DIR / "index.html")
+
+
+@app.get("/metrics")
+def metrics_dashboard() -> FileResponse:
+    """Human-friendly metrics dashboard (fetches /api/metrics with ?token=...)."""
+    return FileResponse(STATIC_DIR / "metrics.html")
+
+
+@app.get("/api/health")
+def health() -> JSONResponse:
+    return JSONResponse(
+        {"ready": bot is not None, "error": INIT_ERROR, "model": getattr(bot, "model", None)}
+    )
+
+
+@app.post("/api/chat")
+def chat(req: ChatRequest) -> JSONResponse:
+    request_id = uuid.uuid4().hex
+    received = time.time()
+
+    if bot is None:
+        monitoring.log_event("api_failure", request_id=request_id,
+                             reason="bot_not_initialised", detail=INIT_ERROR)
+        return JSONResponse(
+            {"error": f"Bot not initialised: {INIT_ERROR}"}, status_code=503
+        )
+    if not req.message.strip():
+        return JSONResponse({"error": "Empty message."}, status_code=400)
+
+    session_id = req.session_id or uuid.uuid4().hex
+    history = SESSIONS.get(session_id, [])
+
+    try:
+        result = bot.chat(history, req.message)
+    except Exception as exc:
+        err = f"{type(exc).__name__}: {exc}"
+        monitoring.log_request(
+            request_id=request_id, session_id=session_id, question=req.message,
+            answer="", latency_ms=(time.time() - received) * 1000,
+            model=getattr(bot, "model", None), llm_calls=0, tokens=None,
+            queries=[], presentation=None, error=err,
+        )
+        monitoring.log_event("api_failure", request_id=request_id,
+                             session_id=session_id, error=err)
+        return JSONResponse({"error": err}, status_code=500)
+
+    SESSIONS[session_id] = result["messages"][-MAX_HISTORY_MESSAGES:]
+    pres = result.get("presentation")
+    usage = result.get("usage") or {}
+    chat_cost = monitoring.cost(usage.get("prompt", 0), usage.get("completion", 0))
+
+    monitoring.log_request(
+        request_id=request_id, session_id=session_id, question=req.message,
+        answer=result["answer"], latency_ms=(time.time() - received) * 1000,
+        model=getattr(bot, "model", None), llm_calls=result.get("llm_calls", 0),
+        tokens=result.get("usage"), queries=result["queries"],
+        presentation=(pres or {}).get("format"), error=None,
+    )
+
+    return JSONResponse(
+        {
+            "session_id": session_id,
+            "request_id": request_id,
+            "answer": result["answer"],
+            "queries": result["queries"],
+            "presentation": pres,
+            "tokens": usage.get("total", 0),
+            "cost_usd": chat_cost,
+        }
+    )
+
+
+@app.get("/api/metrics")
+def metrics(
+    x_metrics_token: str | None = Header(default=None),
+    token: str | None = None,  # query param, for viewing in a browser
+) -> JSONResponse:
+    """Aggregate metrics (uptime, requests, errors, tokens, latency, cost, sessions).
+    If METRICS_TOKEN is set, supply it via the X-Metrics-Token header OR a
+    ?token=... query parameter (the query param is handy in a browser)."""
+    supplied = x_metrics_token or token
+    if config.METRICS_TOKEN and supplied != config.METRICS_TOKEN:
+        return JSONResponse({"error": "Unauthorized"}, status_code=401)
+    return JSONResponse(monitoring.get_metrics())
+
+
+@app.get("/api/metrics/recent")
+def metrics_recent(
+    limit: int = 20,
+    x_metrics_token: str | None = Header(default=None),
+    token: str | None = None,
+) -> JSONResponse:
+    """Recent chats from the durable log (survives restarts). Token-protected."""
+    supplied = x_metrics_token or token
+    if config.METRICS_TOKEN and supplied != config.METRICS_TOKEN:
+        return JSONResponse({"error": "Unauthorized"}, status_code=401)
+    return JSONResponse({"recent": monitoring.recent_chats(min(max(limit, 1), 100))})
+
+
+@app.post("/api/reset")
+def reset(req: ResetRequest) -> JSONResponse:
+    SESSIONS.pop(req.session_id, None)
+    return JSONResponse({"ok": True})
+
+
+# Serve any other static assets (none required, but handy for extension).
+if STATIC_DIR.exists():
+    app.mount("/static", StaticFiles(directory=STATIC_DIR), name="static")

config.py

@@ -0,0 +1,66 @@
+"""Central configuration, loaded from the environment / .env file."""
+import os
+
+from dotenv import load_dotenv
+
+load_dotenv()
+
+
+def _require(name: str) -> str:
+    value = os.getenv(name)
+    if not value:
+        raise RuntimeError(
+            f"Missing required environment variable {name!r}. "
+            "Copy .env.example to .env and fill it in."
+        )
+    return value
+
+
+# --- Database ---
+DB_SERVER = _require("DB_SERVER")
+DB_PORT = os.getenv("DB_PORT", "1433")
+DB_NAME = _require("DB_NAME")
+DB_USER = _require("DB_USER")
+DB_PASSWORD = _require("DB_PASSWORD")
+DB_DRIVER = os.getenv("DB_DRIVER", "ODBC Driver 18 for SQL Server")
+
+# --- LLM backend (OpenAI-compatible: Groq, ngrok AI Gateway, OpenAI, etc.) ---
+# Default: Groq free tier. Swap LLM_BASE_URL/LLM_MODEL to use another backend.
+LLM_BASE_URL = os.getenv("LLM_BASE_URL", "https://api.groq.com/openai/v1")
+LLM_API_KEY = os.getenv("LLM_API_KEY", "")
+LLM_MODEL = os.getenv("LLM_MODEL", "llama-3.3-70b-versatile")
+
+# Price per 1M tokens for cost roll-ups (defaults = Groq Llama 3.3 70B paid rate).
+# On the free tier your real cost is $0 — these power the projected-cost metric.
+LLM_PRICE_IN = float(os.getenv("LLM_PRICE_IN", "0.59"))
+LLM_PRICE_OUT = float(os.getenv("LLM_PRICE_OUT", "0.79"))
+
+# --- Monitoring ---
+# If set, /api/metrics requires header  X-Metrics-Token: <this>  (empty = open).
+METRICS_TOKEN = os.getenv("METRICS_TOKEN", "")
+
+# --- Behaviour ---
+MAX_RESULT_ROWS = int(os.getenv("MAX_RESULT_ROWS", "200"))
+QUERY_TIMEOUT = int(os.getenv("QUERY_TIMEOUT", "30"))
+
+# Comma-separated list of web origins allowed to call the API (for embedding the
+# widget on another site). Use "*" for any origin (dev only). In production set
+# this to your site, e.g. "https://www.antern.com,https://antern.com".
+ALLOWED_ORIGINS = [
+    o.strip() for o in os.getenv("ALLOWED_ORIGINS", "*").split(",") if o.strip()
+]
+
+
+def connection_string() -> str:
+    """Build a pyodbc connection string. Password is wrapped in braces so
+    special characters (e.g. & in the password) are handled safely."""
+    return (
+        f"DRIVER={{{DB_DRIVER}}};"
+        f"SERVER={DB_SERVER},{DB_PORT};"
+        f"DATABASE={DB_NAME};"
+        f"UID={DB_USER};"
+        f"PWD={{{DB_PASSWORD}}};"
+        "Encrypt=yes;"
+        "TrustServerCertificate=yes;"
+        f"Connection Timeout=15;"
+    )

db.py

@@ -0,0 +1,222 @@
+"""Database access layer.
+
+Two responsibilities:
+  1. Introspect the schema once at startup (cached) so the bot can be told
+     what tables/columns/relationships exist.
+  2. Execute model-generated SQL safely: READ-ONLY, single statement, row-capped.
+
+The read-only guard is the core safety mechanism. We connect with a single
+login, so we cannot rely on database-level permissions; instead every query is
+validated to be a single SELECT/WITH statement before it ever reaches the server.
+"""
+from __future__ import annotations
+
+import datetime
+import decimal
+import re
+import struct
+import uuid
+from collections import OrderedDict
+
+import pyodbc
+
+import config
+
+# SQL Server's datetimeoffset (ODBC type -155) isn't decoded by pyodbc natively;
+# without this converter, selecting any CreatedDate/ModifiedDate/DeletedDate
+# column raises "ODBC SQL type -155 is not yet supported". Decode the 20-byte
+# SQL_SS_TIMESTAMPOFFSET struct into a tz-aware datetime.
+SQL_SS_TIMESTAMPOFFSET = -155
+
+
+def _decode_datetimeoffset(raw: bytes):
+    try:
+        y, mo, d, h, mi, s, frac, tzh, tzm = struct.unpack("<6hI2h", raw)
+        return datetime.datetime(
+            y, mo, d, h, mi, s, frac // 1000,
+            datetime.timezone(datetime.timedelta(hours=tzh, minutes=tzm)),
+        )
+    except Exception:
+        return None
+
+
+class UnsafeQueryError(Exception):
+    """Raised when a query fails the read-only safety checks."""
+
+
+# Whole-word keywords that must never appear in a query. SELECT INTO (which
+# creates a table) is covered by the INTO entry.
+_FORBIDDEN = [
+    "INSERT", "UPDATE", "DELETE", "DROP", "ALTER", "CREATE", "TRUNCATE",
+    "MERGE", "EXEC", "EXECUTE", "GRANT", "REVOKE", "DENY", "BACKUP",
+    "RESTORE", "INTO", "SHUTDOWN", "RECONFIGURE", "WAITFOR",
+]
+_FORBIDDEN_RE = re.compile(r"\b(" + "|".join(_FORBIDDEN) + r")\b", re.IGNORECASE)
+# Stored-procedure prefixes (sp_, xp_) used for system access.
+_PROC_RE = re.compile(r"\b(sp_|xp_)\w+", re.IGNORECASE)
+_COMMENT_BLOCK = re.compile(r"/\*.*?\*/", re.DOTALL)
+_COMMENT_LINE = re.compile(r"--[^\n]*")
+
+
+def _connect() -> pyodbc.Connection:
+    conn = pyodbc.connect(config.connection_string(), timeout=15)
+    conn.timeout = config.QUERY_TIMEOUT  # query (command) timeout in seconds
+    conn.add_output_converter(SQL_SS_TIMESTAMPOFFSET, _decode_datetimeoffset)
+    return conn
+
+
+def _strip_comments(sql: str) -> str:
+    sql = _COMMENT_BLOCK.sub(" ", sql)
+    sql = _COMMENT_LINE.sub(" ", sql)
+    return sql
+
+
+def validate_readonly(sql: str) -> str:
+    """Validate that `sql` is a single read-only statement. Returns the cleaned
+    SQL (no trailing semicolon) or raises UnsafeQueryError."""
+    if not sql or not sql.strip():
+        raise UnsafeQueryError("Empty query.")
+
+    cleaned = _strip_comments(sql).strip()
+
+    # Disallow stacked statements: a semicolon is only allowed as the very
+    # last character.
+    body = cleaned[:-1] if cleaned.endswith(";") else cleaned
+    if ";" in body:
+        raise UnsafeQueryError(
+            "Multiple statements are not allowed. Send a single SELECT query."
+        )
+
+    first = body.lstrip().split(None, 1)[0].upper() if body.strip() else ""
+    if first not in ("SELECT", "WITH"):
+        raise UnsafeQueryError(
+            "Only SELECT (or WITH ... SELECT) queries are allowed."
+        )
+
+    if _FORBIDDEN_RE.search(body):
+        bad = _FORBIDDEN_RE.search(body).group(1).upper()
+        raise UnsafeQueryError(f"Disallowed keyword in query: {bad}.")
+
+    if _PROC_RE.search(body):
+        raise UnsafeQueryError("Stored-procedure calls are not allowed.")
+
+    return body
+
+
+def _jsonify(value):
+    """Convert SQL Server values into JSON-serialisable Python values."""
+    if value is None:
+        return None
+    if isinstance(value, (datetime.datetime, datetime.date, datetime.time)):
+        return value.isoformat()
+    if isinstance(value, decimal.Decimal):
+        # keep integers as ints, others as float
+        return int(value) if value == value.to_integral_value() else float(value)
+    if isinstance(value, uuid.UUID):
+        return str(value)
+    if isinstance(value, (bytes, bytearray)):
+        return value.hex()
+    return value
+
+
+def run_query(sql: str) -> dict:
+    """Validate and execute a read-only query.
+
+    Returns a dict: {columns: [...], rows: [[...]], row_count, truncated}.
+    """
+    body = validate_readonly(sql)
+    conn = _connect()
+    try:
+        cur = conn.cursor()
+        cur.execute(body)
+        if cur.description is None:
+            return {"columns": [], "rows": [], "row_count": 0, "truncated": False}
+        columns = [d[0] for d in cur.description]
+        cap = config.MAX_RESULT_ROWS
+        raw = cur.fetchmany(cap + 1)
+        truncated = len(raw) > cap
+        raw = raw[:cap]
+        rows = [[_jsonify(v) for v in row] for row in raw]
+        return {
+            "columns": columns,
+            "rows": rows,
+            "row_count": len(rows),
+            "truncated": truncated,
+        }
+    finally:
+        conn.close()
+
+
+def introspect_schema() -> str:
+    """Build a compact text description of the schema for the system prompt:
+    every table with its columns, plus foreign-key relationships."""
+    conn = _connect()
+    try:
+        cur = conn.cursor()
+        cur.execute(
+            """
+            SELECT t.TABLE_NAME, c.COLUMN_NAME, c.DATA_TYPE
+            FROM INFORMATION_SCHEMA.TABLES t
+            JOIN INFORMATION_SCHEMA.COLUMNS c
+              ON t.TABLE_NAME = c.TABLE_NAME AND t.TABLE_SCHEMA = c.TABLE_SCHEMA
+            WHERE t.TABLE_TYPE = 'BASE TABLE'
+            ORDER BY t.TABLE_NAME, c.ORDINAL_POSITION
+            """
+        )
+        # Boilerplate audit columns present on nearly every table — omitted from
+        # the listing to save prompt tokens (IsActive is kept; it's meaningful).
+        AUDIT_COLS = {
+            "CreatedBy", "CreatedDate", "ModifiedBy", "ModifiedDate",
+            "DeletedBy", "DeletedDate",
+        }
+        tables: "OrderedDict[str, list[str]]" = OrderedDict()
+        for tname, cname, dtype in cur.fetchall():
+            if cname in AUDIT_COLS:
+                continue
+            tables.setdefault(tname, []).append(f"{cname} {dtype}")
+
+        # Foreign keys for join hints.
+        cur.execute(
+            """
+            SELECT
+                fk_tab.name AS fk_table, fk_col.name AS fk_column,
+                pk_tab.name AS pk_table, pk_col.name AS pk_column
+            FROM sys.foreign_key_columns fkc
+            JOIN sys.tables fk_tab ON fkc.parent_object_id = fk_tab.object_id
+            JOIN sys.columns fk_col
+              ON fkc.parent_object_id = fk_col.object_id
+             AND fkc.parent_column_id = fk_col.column_id
+            JOIN sys.tables pk_tab ON fkc.referenced_object_id = pk_tab.object_id
+            JOIN sys.columns pk_col
+              ON fkc.referenced_object_id = pk_col.object_id
+             AND fkc.referenced_column_id = pk_col.column_id
+            ORDER BY fk_tab.name, fk_col.name
+            """
+        )
+        fks = [
+            f"{r.fk_table}.{r.fk_column} -> {r.pk_table}.{r.pk_column}"
+            for r in cur.fetchall()
+        ]
+    finally:
+        conn.close()
+
+    lines = ["# Tables (table(column type, ...))", ""]
+    for tname, cols in tables.items():
+        lines.append(f"{tname}({', '.join(cols)})")
+    if fks:
+        lines.append("")
+        lines.append("# Foreign keys (from -> to)")
+        lines.append("")
+        lines.extend(fks)
+    return "\n".join(lines)
+
+
+def ping() -> str:
+    """Quick connectivity check; returns the server version."""
+    conn = _connect()
+    try:
+        cur = conn.cursor()
+        cur.execute("SELECT @@VERSION")
+        return cur.fetchone()[0]
+    finally:
+        conn.close()

monitoring.py

@@ -0,0 +1,248 @@
+"""Monitoring & logging for Antern Bot.
+
+Writes one structured JSON line per event to logs/antern.jsonl (and to the
+console), and keeps in-memory aggregate counters exposed via /api/metrics.
+
+Per chat request we record:
+  - when the request was received + how long it took (latency_ms)
+  - which model was used + how many LLM calls
+  - tokens consumed (prompt / completion / total, from the LLM response)
+  - the SQL executed and row counts
+  - security events (read-only guard blocking a query)
+  - errors / API failures
+  - CPU & RAM utilisation (GPU N/A — the LLM runs remotely on Groq)
+  - a full audit trail (session_id, question, answer length)
+"""
+from __future__ import annotations
+
+import datetime
+import json
+import logging
+import threading
+import time
+from pathlib import Path
+
+import config
+
+try:
+    import psutil
+except ImportError:  # optional dependency
+    psutil = None
+
+LOG_DIR = Path(__file__).parent / "logs"
+LOG_DIR.mkdir(exist_ok=True)
+LOG_FILE = LOG_DIR / "antern.jsonl"
+
+# --- JSON-lines logger (file + console) ---
+logger = logging.getLogger("antern.monitor")
+if not logger.handlers:  # guard against duplicate handlers on reload
+    logger.setLevel(logging.INFO)
+    _fmt = logging.Formatter("%(message)s")
+    _fh = logging.FileHandler(LOG_FILE, encoding="utf-8")
+    _fh.setFormatter(_fmt)
+    logger.addHandler(_fh)
+    _ch = logging.StreamHandler()
+    _ch.setFormatter(_fmt)
+    logger.addHandler(_ch)
+    logger.propagate = False
+
+# --- In-memory aggregate counters (reset on restart) ---
+_lock = threading.Lock()
+_metrics = {
+    "started": time.time(),
+    "requests": 0,
+    "errors": 0,
+    "blocked_queries": 0,
+    "sql_errors": 0,
+    "tokens_total": 0,
+    "latency_ms_sum": 0.0,
+    "cost_usd_sum": 0.0,
+}
+# Per-session roll-up: session_id -> {requests, prompt, completion, total, cost_usd}
+_sessions: dict[str, dict] = {}
+
+
+def _cost(prompt: int, completion: int) -> float:
+    """Projected $ cost from token counts and configured per-1M prices."""
+    return round(
+        prompt / 1e6 * config.LLM_PRICE_IN + completion / 1e6 * config.LLM_PRICE_OUT,
+        6,
+    )
+
+
+def cost(prompt: int, completion: int) -> float:
+    """Public alias for computing a chat's projected $ cost."""
+    return _cost(prompt, completion)
+
+
+def _now() -> str:
+    return datetime.datetime.now(datetime.timezone.utc).isoformat()
+
+
+def system_stats() -> dict:
+    """CPU and RAM utilisation. GPU is not tracked (LLM is remote; no local GPU)."""
+    if not psutil:
+        return {}
+    return {
+        "cpu_pct": psutil.cpu_percent(interval=None),
+        "ram_pct": psutil.virtual_memory().percent,
+    }
+
+
+def _write(record: dict) -> None:
+    record.setdefault("ts", _now())
+    logger.info(json.dumps(record, default=str))
+
+
+def log_event(event: str, **fields) -> None:
+    """Log a discrete event (e.g. security, api_failure, startup)."""
+    _write({"event": event, **fields})
+
+
+def log_request(
+    *,
+    request_id: str,
+    session_id: str,
+    question: str,
+    answer: str,
+    latency_ms: float,
+    model: str | None,
+    llm_calls: int,
+    tokens: dict | None,
+    queries: list[dict],
+    presentation: str | None,
+    error: str | None,
+) -> None:
+    """Record one chat request (the audit trail) and update aggregate counters."""
+    blocked = [q for q in queries if str(q.get("error", "")).startswith("Blocked")]
+    sql_errored = [
+        q for q in queries
+        if q.get("error") and not str(q.get("error")).startswith("Blocked")
+    ]
+
+    p = (tokens or {}).get("prompt", 0)
+    comp = (tokens or {}).get("completion", 0)
+    tot = (tokens or {}).get("total", 0)
+    cost = _cost(p, comp)
+
+    with _lock:
+        _metrics["requests"] += 1
+        _metrics["latency_ms_sum"] += latency_ms
+        _metrics["tokens_total"] += tot
+        _metrics["cost_usd_sum"] += cost
+        _metrics["blocked_queries"] += len(blocked)
+        _metrics["sql_errors"] += len(sql_errored)
+        if error:
+            _metrics["errors"] += 1
+        s = _sessions.setdefault(
+            session_id,
+            {"requests": 0, "prompt": 0, "completion": 0, "total": 0, "cost_usd": 0.0},
+        )
+        s["requests"] += 1
+        s["prompt"] += p
+        s["completion"] += comp
+        s["total"] += tot
+        s["cost_usd"] = round(s["cost_usd"] + cost, 6)
+
+    # Emit a discrete security event for each blocked (write-attempt) query.
+    for q in blocked:
+        log_event(
+            "security",
+            request_id=request_id,
+            session_id=session_id,
+            reason=q.get("error"),
+            query=q.get("query"),
+        )
+
+    _write({
+        "event": "chat",
+        "request_id": request_id,
+        "session_id": session_id,
+        "question": question,
+        "answer_chars": len(answer or ""),
+        "latency_ms": round(latency_ms, 1),
+        "model": model,
+        "llm_calls": llm_calls,
+        "tokens": tokens,
+        "cost_usd": cost,
+        "sql": [
+            {"query": q.get("query"), "row_count": q.get("row_count"),
+             "error": q.get("error")}
+            for q in queries
+        ],
+        "presentation": presentation,
+        "security_events": len(blocked),
+        "sql_errors": len(sql_errored),
+        "error": error,
+        "system": system_stats(),
+    })
+
+
+def top_sessions(n: int = 10) -> list[dict]:
+    """Per-session cost roll-up, highest cost first."""
+    with _lock:
+        items = [{"session_id": sid, **vals} for sid, vals in _sessions.items()]
+    items.sort(key=lambda x: x["cost_usd"], reverse=True)
+    return items[:n]
+
+
+def recent_chats(n: int = 20) -> list[dict]:
+    """Read the last `n` chat records from the log file (most recent first).
+    Sourced from the log, so it survives restarts (unlike the live counters)."""
+    if not LOG_FILE.exists():
+        return []
+    try:
+        lines = LOG_FILE.read_text(encoding="utf-8").splitlines()
+    except Exception:
+        return []
+    out: list[dict] = []
+    for line in reversed(lines):
+        if '"chat"' not in line:
+            continue
+        try:
+            rec = json.loads(line)
+        except Exception:
+            continue
+        if rec.get("event") != "chat":
+            continue
+        out.append({
+            "ts": rec.get("ts"),
+            "session_id": rec.get("session_id"),
+            "question": rec.get("question"),
+            "latency_ms": rec.get("latency_ms"),
+            "tokens": (rec.get("tokens") or {}).get("total"),
+            "cost_usd": rec.get("cost_usd"),
+            "presentation": rec.get("presentation"),
+            "security_events": rec.get("security_events", 0),
+            "sql_errors": rec.get("sql_errors", 0),
+            "error": rec.get("error"),
+        })
+        if len(out) >= n:
+            break
+    return out
+
+
+def get_metrics() -> dict:
+    """Aggregate counters for /api/metrics."""
+    with _lock:
+        m = dict(_metrics)
+        n_sessions = len(_sessions)
+    uptime = time.time() - m["started"]
+    reqs = m["requests"]
+    return {
+        "uptime_seconds": round(uptime, 1),
+        "requests": reqs,
+        "sessions": n_sessions,
+        "errors": m["errors"],
+        "error_rate": round(m["errors"] / reqs, 3) if reqs else 0,
+        "blocked_queries": m["blocked_queries"],
+        "sql_errors": m["sql_errors"],
+        "tokens_total": m["tokens_total"],
+        "avg_latency_ms": round(m["latency_ms_sum"] / reqs, 1) if reqs else 0,
+        "avg_tokens_per_request": round(m["tokens_total"] / reqs, 1) if reqs else 0,
+        "total_cost_usd": round(m["cost_usd_sum"], 6),
+        "avg_cost_per_request_usd": round(m["cost_usd_sum"] / reqs, 6) if reqs else 0,
+        "price_per_1m": {"input": config.LLM_PRICE_IN, "output": config.LLM_PRICE_OUT},
+        "top_sessions": top_sessions(10),
+        "system": system_stats(),
+    }

requirements.txt

@@ -0,0 +1,6 @@
+fastapi>=0.136.0
+uvicorn[standard]>=0.49.0
+pyodbc>=5.2.0
+openai>=1.50.0
+python-dotenv>=1.0.1
+psutil>=5.9.0

run.ps1

@@ -0,0 +1,2 @@
+# Launch Antern Bot
+python -m uvicorn app:app --host 127.0.0.1 --port 8000

static/demo.html

@@ -0,0 +1,35 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+<title>Embed demo — your website</title>
+<style>
+  body { font-family: Georgia, serif; margin: 0; color: #222; background: #fafafa; }
+  .hero { max-width: 760px; margin: 0 auto; padding: 80px 24px; }
+  h1 { font-size: 38px; }
+  p { font-size: 18px; line-height: 1.7; color: #444; }
+  .note { background: #fff; border: 1px solid #e5e5e5; border-radius: 10px; padding: 16px 20px; margin-top: 30px; font-size: 15px; }
+  code { background: #f0f0f0; padding: 2px 6px; border-radius: 4px; font-family: monospace; }
+</style>
+</head>
+<body>
+  <div class="hero">
+    <h1>This is a pretend website.</h1>
+    <p>Imagine this is your company's webpage. The only thing added to it is a
+       single <code>&lt;script&gt;</code> tag at the bottom — and now there's an
+       Antern Bot chat button in the corner. Click the 💬 button bottom-right.</p>
+    <div class="note">
+      The chat bubble is the embeddable widget. On a real site you'd paste the
+      one-line snippet from <code>EMBED.md</code> into your HTML.
+    </div>
+  </div>
+
+  <!-- The embed snippet (served from the same host in this demo) -->
+  <script src="/static/widget.js"
+          data-api=""
+          data-title="Antern Bot"
+          data-accent="#4f8cff"
+          data-greeting="Hi! Ask me about candidates, requirements, applications, and more."></script>
+</body>
+</html>

static/embed-inline.html

@@ -0,0 +1,279 @@
+<!-- ======================================================================
+     ANTERN BOT — embeddable chat widget (inline build for ngrok free tier)
+
+     HOW TO USE:
+       Copy the entire <script>...</script> block below and paste it just
+       before the closing </body> tag on any page of your website.
+
+     Why inline? ngrok's free tier shows a browser-warning page on a normal
+     <script src="...ngrok...">, so the widget code is inlined here instead.
+     The only call that touches ngrok is the chat API request, which sends the
+     "ngrok-skip-browser-warning" header and works fine. (Chart.js, when a chart
+     is shown, loads from the jsDelivr CDN — not from ngrok.)
+
+     To change the bot URL, title, colour, or greeting, edit the four CONFIG
+     lines at the top of the script.
+     ====================================================================== -->
+<script>
+(function () {
+  /* ---- CONFIG (edit these) ---- */
+  var API = "https://duckling-bovine-blitz.ngrok-free.dev"; // your stable bot URL
+  var TITLE = "Antern Bot";
+  var ACCENT = "#4f8cff";
+  var GREETING = "👋 Hi! I'm Antern Bot, your data assistant.\n\nAsk me anything about your recruitment data — candidates, requirements, applications, interviews — in plain English.\n\nTry: “How many active candidates do we have?”";
+  /* ----------------------------- */
+  var STORAGE_KEY = "antern_bot_session";
+  API = API.replace(/\/$/, "");
+
+  var host = document.createElement("div");
+  host.id = "antern-bot-widget";
+  document.body.appendChild(host);
+  var root = host.attachShadow({ mode: "open" });
+
+  root.innerHTML =
+    '<style>' +
+    ':host{all:initial;}' +
+    '*{box-sizing:border-box;font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif;}' +
+    '.launcher{position:fixed;bottom:24px;right:24px;width:62px;height:62px;border-radius:50%;border:none;cursor:pointer;background:linear-gradient(135deg,' + ACCENT + ',#8a5cff);color:#fff;z-index:2147483000;display:flex;align-items:center;justify-content:center;box-shadow:0 10px 28px rgba(0,0,0,.30),0 4px 12px rgba(79,140,255,.45);transition:transform .25s cubic-bezier(.2,.9,.3,1.2),box-shadow .25s;animation:antern-pop .5s cubic-bezier(.2,.9,.3,1.2);}' +
+    '.launcher::after{content:"";position:absolute;inset:0;border-radius:50%;background:linear-gradient(135deg,' + ACCENT + ',#8a5cff);z-index:-1;animation:antern-pulse 2.6s ease-out infinite;}' +
+    '.launcher.open::after{animation:none;opacity:0;}' +
+    '.launcher:hover{transform:translateY(-3px) scale(1.05);box-shadow:0 16px 38px rgba(0,0,0,.34),0 6px 18px rgba(79,140,255,.55);}' +
+    '.launcher:active{transform:translateY(-1px) scale(.97);}' +
+    '.launcher svg{width:27px;height:27px;}' +
+    '.launcher .ic-close{display:none;}' +
+    '.launcher.open .ic-chat{display:none;}' +
+    '.launcher.open .ic-close{display:block;}' +
+    '@keyframes antern-pop{0%{transform:scale(0) rotate(-25deg);}100%{transform:scale(1) rotate(0);}}' +
+    '@keyframes antern-pulse{0%{transform:scale(1);opacity:.45;}70%{transform:scale(1.7);opacity:0;}100%{opacity:0;}}' +
+    '.panel{position:fixed;bottom:92px;right:22px;width:760px;max-width:calc(100vw - 32px);height:1120px;max-height:calc(100vh - 120px);background:#0f1115;border:1px solid #2a303c;border-radius:16px;box-shadow:0 12px 40px rgba(0,0,0,.4);z-index:2147483000;display:none;flex-direction:column;overflow:hidden;}' +
+    '.panel.open{display:flex;}' +
+    '.head{background:#171a21;border-bottom:1px solid #2a303c;padding:13px 16px;display:flex;align-items:center;gap:10px;color:#e8eaed;}' +
+    '.head .badge{width:28px;height:28px;border-radius:8px;background:' + ACCENT + ';display:flex;align-items:center;justify-content:center;font-weight:700;}' +
+    '.head h3{margin:0;font-size:15px;flex:1;}' +
+    '.head button{background:none;border:none;color:#9aa3b2;cursor:pointer;font-size:20px;line-height:1;}' +
+    '.body{flex:1;overflow-y:auto;padding:16px;background:#0f1115;}' +
+    '.msg{display:flex;gap:9px;margin-bottom:14px;}' +
+    '.msg .av{width:26px;height:26px;border-radius:7px;flex-shrink:0;display:flex;align-items:center;justify-content:center;font-size:11px;font-weight:700;color:#fff;}' +
+    '.msg.bot .av{background:' + ACCENT + ';}' +
+    '.msg.user .av{background:#374151;}' +
+    '.bubble{background:#232936;border:1px solid #2a303c;border-radius:11px;padding:10px 13px;color:#e8eaed;font-size:14px;line-height:1.5;white-space:pre-wrap;word-wrap:break-word;max-width:100%;}' +
+    '.msg.user .bubble{background:#1f242e;}' +
+    '.typing{color:#9aa3b2;font-style:italic;}' +
+    '.foot{border-top:1px solid #2a303c;background:#171a21;padding:11px;display:flex;gap:8px;}' +
+    '.foot textarea{flex:1;resize:none;background:#1f242e;color:#e8eaed;border:1px solid #2a303c;border-radius:9px;padding:9px 11px;font-size:14px;max-height:120px;}' +
+    '.foot textarea:focus{outline:none;border-color:' + ACCENT + ';}' +
+    '.foot button{background:' + ACCENT + ';color:#fff;border:none;border-radius:9px;padding:0 16px;font-weight:600;cursor:pointer;font-size:14px;}' +
+    '.foot button:disabled{opacity:.5;cursor:not-allowed;}' +
+    '.cap{font-size:11.5px;color:#9aa3b2;margin:10px 0 4px;}' +
+    '.tbl-wrap{margin-top:8px;max-height:260px;overflow:auto;border:1px solid #2a303c;border-radius:9px;}' +
+    'table.tbl{border-collapse:collapse;width:100%;font-size:12.5px;}' +
+    'table.tbl th,table.tbl td{padding:6px 9px;border-bottom:1px solid #2a303c;text-align:left;white-space:nowrap;}' +
+    'table.tbl th{position:sticky;top:0;background:#1f242e;color:#cbd5e1;font-weight:600;}' +
+    'table.tbl td{color:#e8eaed;}' +
+    'table.tbl tr:hover td{background:#1a1f29;}' +
+    '.chart-wrap{margin-top:8px;background:#fff;border-radius:9px;padding:10px;}' +
+    '.chart-wrap canvas{max-width:100%;}' +
+    '.stats{padding:7px 12px;background:#12151b;border-top:1px solid #2a303c;color:#9aa3b2;font-size:11px;text-align:center;}' +
+    '</style>' +
+    '<button class="launcher" aria-label="Open chat">' +
+    '<svg class="ic-chat" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M21 11.5a8.5 8.5 0 0 1-12.5 7.48L3 21l2.02-5.5A8.5 8.5 0 1 1 21 11.5z"/><circle cx="8.5" cy="11.5" r="1" fill="currentColor" stroke="none"/><circle cx="12" cy="11.5" r="1" fill="currentColor" stroke="none"/><circle cx="15.5" cy="11.5" r="1" fill="currentColor" stroke="none"/></svg>' +
+    '<svg class="ic-close" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.4" stroke-linecap="round" stroke-linejoin="round"><path d="M6 9l6 6 6-6"/></svg>' +
+    '</button>' +
+    '<div class="panel" role="dialog" aria-label="' + TITLE + '">' +
+    '  <div class="head"><div class="badge">A</div><h3>' + TITLE + '</h3><button class="close" aria-label="Close">×</button></div>' +
+    '  <div class="body"></div>' +
+    '  <div class="foot"><textarea rows="1" placeholder="Type your question…"></textarea><button class="send">Send</button></div>' +
+    '  <div class="stats"></div>' +
+    '</div>';
+
+  var launcher = root.querySelector(".launcher");
+  var panel = root.querySelector(".panel");
+  var closeBtn = root.querySelector(".close");
+  var body = root.querySelector(".body");
+  var input = root.querySelector("textarea");
+  var sendBtn = root.querySelector(".send");
+  var statsEl = root.querySelector(".stats");
+  var sessionId = localStorage.getItem(STORAGE_KEY) || null;
+  var greeted = false;
+  var PALETTE = ["#4f8cff","#8a5cff","#38d39f","#ffb020","#ff6b6b","#22b8cf","#f783ac","#a0d911"];
+  var chartJsPromise = null;
+
+  function loadChartJs() {
+    if (window.Chart) return Promise.resolve(window.Chart);
+    if (chartJsPromise) return chartJsPromise;
+    chartJsPromise = new Promise(function (resolve, reject) {
+      var s = document.createElement("script");
+      s.src = "https://cdn.jsdelivr.net/npm/chart.js@4/dist/chart.umd.min.js";
+      s.onload = function () { resolve(window.Chart); };
+      s.onerror = function () { reject(new Error("chart lib failed")); };
+      document.head.appendChild(s);
+    });
+    return chartJsPromise;
+  }
+
+  function renderTable(container, p) {
+    var cols = p.columns || [], rows = p.rows || [];
+    if (p.title) { var c = document.createElement("div"); c.className = "cap"; c.textContent = p.title; container.appendChild(c); }
+    var wrap = document.createElement("div"); wrap.className = "tbl-wrap";
+    var t = document.createElement("table"); t.className = "tbl";
+    var thead = document.createElement("thead"), trh = document.createElement("tr");
+    cols.forEach(function (col) { var th = document.createElement("th"); th.textContent = col; trh.appendChild(th); });
+    thead.appendChild(trh); t.appendChild(thead);
+    var tb = document.createElement("tbody");
+    rows.forEach(function (r) {
+      var tr = document.createElement("tr");
+      r.forEach(function (v) { var td = document.createElement("td"); td.textContent = (v === null || v === undefined) ? "" : v; tr.appendChild(td); });
+      tb.appendChild(tr);
+    });
+    t.appendChild(tb); wrap.appendChild(t); container.appendChild(wrap);
+    if (p.truncated) { var n = document.createElement("div"); n.className = "cap"; n.textContent = "(showing first " + rows.length + " rows)"; container.appendChild(n); }
+  }
+
+  function renderChart(container, p) {
+    var cols = p.columns || [], rows = p.rows || [];
+    var xi = cols.indexOf(p.x_field);
+    var yIdx = (p.y_fields || []).map(function (f) { return cols.indexOf(f); }).filter(function (i) { return i >= 0; });
+    if (xi < 0 || yIdx.length === 0) { renderTable(container, p); return; }
+    if (p.title) { var cap = document.createElement("div"); cap.className = "cap"; cap.textContent = p.title; container.appendChild(cap); }
+    var wrap = document.createElement("div"); wrap.className = "chart-wrap";
+    var canvas = document.createElement("canvas"); wrap.appendChild(canvas); container.appendChild(wrap);
+    var labels = rows.map(function (r) { return r[xi]; });
+    loadChartJs().then(function (Chart) {
+      if (p.format === "pie") {
+        var fi = yIdx[0];
+        new Chart(canvas, {
+          type: "pie",
+          data: { labels: labels, datasets: [{ data: rows.map(function (r) { return Number(r[fi]) || 0; }), backgroundColor: labels.map(function (_, i) { return PALETTE[i % PALETTE.length]; }) }] },
+          options: { responsive: true, plugins: { legend: { position: "right" } } },
+        });
+      } else {
+        var datasets = yIdx.map(function (ci, k) {
+          return { label: cols[ci], data: rows.map(function (r) { return Number(r[ci]) || 0; }), backgroundColor: PALETTE[k % PALETTE.length], borderColor: PALETTE[k % PALETTE.length], fill: false, tension: 0.25 };
+        });
+        new Chart(canvas, {
+          type: p.format === "line" ? "line" : "bar",
+          data: { labels: labels, datasets: datasets },
+          options: { responsive: true, plugins: { legend: { display: yIdx.length > 1 } }, scales: { y: { beginAtZero: true } } },
+        });
+      }
+      body.scrollTop = body.scrollHeight;
+    }).catch(function () {
+      var e = document.createElement("div"); e.className = "cap"; e.textContent = "(couldn't load chart — showing table)"; container.appendChild(e);
+      renderTable(container, p);
+    });
+  }
+
+  function renderPresentation(bubble, p) {
+    if (!p || !p.format || p.format === "text") return;
+    var box = document.createElement("div");
+    bubble.appendChild(box);
+    if (p.format === "table") renderTable(box, p);
+    else renderChart(box, p);
+  }
+
+  var STATS_KEY = "antern_bot_daystats";
+  var lastTokens = null;
+  function _today() { return new Date().toISOString().slice(0, 10); }
+  function getStats() {
+    var s;
+    try { s = JSON.parse(localStorage.getItem(STATS_KEY) || "{}"); } catch (e) { s = {}; }
+    if (s.date !== _today()) s = { date: _today(), chats: 0, cost: 0 };
+    return s;
+  }
+  function bumpStats(cost) {
+    var s = getStats();
+    s.chats += 1; s.cost += (cost || 0);
+    localStorage.setItem(STATS_KEY, JSON.stringify(s));
+  }
+  function renderStats() {
+    var s = getStats();
+    var avg = s.chats ? s.cost / s.chats : 0;
+    var parts = ["Today: " + s.chats + " chat" + (s.chats === 1 ? "" : "s"),
+                 "avg $" + avg.toFixed(4) + "/chat"];
+    if (lastTokens != null) parts.push("last: " + lastTokens.toLocaleString() + " tokens");
+    statsEl.textContent = parts.join("  ·  ");
+  }
+
+  function esc(s) {
+    return (s == null ? "" : String(s)).replace(/[&<>"]/g, function (c) {
+      return { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" }[c];
+    });
+  }
+
+  function addMsg(role, text) {
+    var m = document.createElement("div");
+    m.className = "msg " + role;
+    m.innerHTML =
+      '<div class="av">' + (role === "user" ? "You" : "A") + "</div>" +
+      '<div class="bubble"></div>';
+    m.querySelector(".bubble").textContent = text;
+    body.appendChild(m);
+    body.scrollTop = body.scrollHeight;
+    return m;
+  }
+
+  function setOpen(open) {
+    panel.classList.toggle("open", open);
+    launcher.classList.toggle("open", open);
+    launcher.setAttribute("aria-label", open ? "Close chat" : "Open chat");
+    if (open && !greeted) { addMsg("bot", GREETING); greeted = true; }
+    if (open) { renderStats(); input.focus(); }
+  }
+
+  async function send(text) {
+    addMsg("user", text);
+    sendBtn.disabled = true;
+    var m = addMsg("bot", "");
+    var bubble = m.querySelector(".bubble");
+    bubble.innerHTML = '<span class="typing">Thinking…</span>';
+    try {
+      var r = await fetch(API + "/api/chat", {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "ngrok-skip-browser-warning": "true",
+        },
+        body: JSON.stringify({ message: text, session_id: sessionId }),
+      });
+      var d = await r.json();
+      if (!r.ok) {
+        bubble.innerHTML = '<span class="typing">⚠ ' + esc(d.error || "Error") + "</span>";
+      } else {
+        sessionId = d.session_id;
+        localStorage.setItem(STORAGE_KEY, sessionId);
+        bubble.textContent = d.answer || "(no answer)";
+        renderPresentation(bubble, d.presentation);
+        if (typeof d.cost_usd === "number") bumpStats(d.cost_usd);
+        if (typeof d.tokens === "number") lastTokens = d.tokens;
+        renderStats();
+      }
+    } catch (e) {
+      bubble.innerHTML = '<span class="typing">⚠ Network error</span>';
+    } finally {
+      sendBtn.disabled = false;
+      body.scrollTop = body.scrollHeight;
+    }
+  }
+
+  function submit() {
+    var t = input.value.trim();
+    if (!t) return;
+    input.value = "";
+    input.style.height = "auto";
+    send(t);
+  }
+
+  launcher.addEventListener("click", function () { setOpen(!panel.classList.contains("open")); });
+  closeBtn.addEventListener("click", function () { setOpen(false); });
+  sendBtn.addEventListener("click", submit);
+  input.addEventListener("keydown", function (e) {
+    if (e.key === "Enter" && !e.shiftKey) { e.preventDefault(); submit(); }
+  });
+  input.addEventListener("input", function () {
+    input.style.height = "auto";
+    input.style.height = Math.min(input.scrollHeight, 120) + "px";
+  });
+
+  renderStats();
+})();
+</script>

static/index.html

@@ -0,0 +1,200 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+<title>Antern Bot</title>
+<style>
+  :root {
+    --bg: #0f1115; --panel: #171a21; --panel2: #1f242e; --border: #2a303c;
+    --text: #e8eaed; --muted: #9aa3b2; --accent: #4f8cff; --user: #2563eb;
+    --bot: #232936; --danger: #ff6b6b; --code: #11151c;
+  }
+  * { box-sizing: border-box; }
+  body {
+    margin: 0; font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+    background: var(--bg); color: var(--text); height: 100vh; display: flex; flex-direction: column;
+  }
+  header {
+    padding: 14px 20px; background: var(--panel); border-bottom: 1px solid var(--border);
+    display: flex; align-items: center; gap: 12px;
+  }
+  header .logo { width: 30px; height: 30px; border-radius: 8px; background: linear-gradient(135deg, #4f8cff, #8a5cff); display: flex; align-items: center; justify-content: center; font-weight: 700; }
+  header h1 { font-size: 16px; margin: 0; }
+  header .sub { font-size: 12px; color: var(--muted); margin-left: 2px; }
+  header .spacer { flex: 1; }
+  header button { background: var(--panel2); color: var(--text); border: 1px solid var(--border); border-radius: 8px; padding: 7px 12px; cursor: pointer; font-size: 13px; }
+  header button:hover { border-color: var(--accent); }
+  #status { font-size: 12px; color: var(--muted); }
+  #status .dot { display: inline-block; width: 8px; height: 8px; border-radius: 50%; background: var(--muted); margin-right: 5px; }
+  #status.ok .dot { background: #38d39f; }
+  #status.bad .dot { background: var(--danger); }
+
+  main { flex: 1; overflow-y: auto; padding: 24px 0; }
+  .wrap { max-width: 820px; margin: 0 auto; padding: 0 20px; }
+  .msg { display: flex; margin-bottom: 18px; gap: 12px; }
+  .msg .avatar { width: 30px; height: 30px; border-radius: 8px; flex-shrink: 0; display: flex; align-items: center; justify-content: center; font-size: 13px; font-weight: 700; }
+  .msg.user .avatar { background: var(--user); }
+  .msg.bot .avatar { background: linear-gradient(135deg, #4f8cff, #8a5cff); }
+  .bubble { background: var(--bot); border: 1px solid var(--border); border-radius: 12px; padding: 12px 15px; line-height: 1.55; white-space: pre-wrap; word-wrap: break-word; max-width: 100%; }
+  .msg.user .bubble { background: var(--panel2); }
+  .queries { margin-top: 10px; }
+  .queries summary { cursor: pointer; color: var(--muted); font-size: 12px; }
+  .queries pre { background: var(--code); border: 1px solid var(--border); border-radius: 8px; padding: 10px; overflow-x: auto; font-size: 12.5px; margin: 8px 0 0; color: #cbd5e1; }
+  .queries .meta { font-size: 11.5px; color: var(--muted); margin-top: 4px; }
+  .queries .err { color: var(--danger); }
+  .typing { color: var(--muted); font-style: italic; }
+
+  footer { border-top: 1px solid var(--border); background: var(--panel); padding: 14px 0; }
+  form { max-width: 820px; margin: 0 auto; padding: 0 20px; display: flex; gap: 10px; }
+  textarea { flex: 1; resize: none; background: var(--panel2); color: var(--text); border: 1px solid var(--border); border-radius: 10px; padding: 11px 13px; font-size: 14px; font-family: inherit; max-height: 160px; }
+  textarea:focus { outline: none; border-color: var(--accent); }
+  form button { background: var(--accent); color: #fff; border: none; border-radius: 10px; padding: 0 20px; font-size: 14px; font-weight: 600; cursor: pointer; }
+  form button:disabled { opacity: 0.5; cursor: not-allowed; }
+  .hint { max-width: 820px; margin: 8px auto 0; padding: 0 20px; font-size: 11.5px; color: var(--muted); }
+</style>
+</head>
+<body>
+  <header>
+    <div class="logo">A</div>
+    <div>
+      <h1>Antern Bot</h1>
+      <div class="sub">Ask about the IAmInterviewed_QA database in plain English</div>
+    </div>
+    <div class="spacer"></div>
+    <div id="status"><span class="dot"></span><span id="status-text">connecting…</span></div>
+    <button id="reset">New chat</button>
+  </header>
+
+  <main id="main">
+    <div class="wrap" id="messages"></div>
+  </main>
+
+  <footer>
+    <form id="form">
+      <textarea id="input" rows="1" placeholder="e.g. How many active candidates are there?" autocomplete="off"></textarea>
+      <button type="submit" id="send">Send</button>
+    </form>
+    <div class="hint">Read-only — the bot can only run SELECT queries. Press Enter to send, Shift+Enter for a new line.</div>
+  </footer>
+
+<script>
+  const messagesEl = document.getElementById('messages');
+  const form = document.getElementById('form');
+  const input = document.getElementById('input');
+  const sendBtn = document.getElementById('send');
+  const resetBtn = document.getElementById('reset');
+  const statusEl = document.getElementById('status');
+  const statusText = document.getElementById('status-text');
+  let sessionId = null;
+
+  function esc(s) {
+    return (s ?? '').replace(/[&<>"]/g, c => ({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;'}[c]));
+  }
+
+  function addMessage(role, text) {
+    const msg = document.createElement('div');
+    msg.className = 'msg ' + role;
+    const avatar = role === 'user' ? 'You' : 'A';
+    msg.innerHTML = `<div class="avatar">${avatar}</div><div class="bubble"></div>`;
+    msg.querySelector('.bubble').textContent = text;
+    messagesEl.appendChild(msg);
+    scroll();
+    return msg;
+  }
+
+  function renderQueries(bubble, queries) {
+    if (!queries || !queries.length) return;
+    const det = document.createElement('details');
+    det.className = 'queries';
+    let inner = `<summary>${queries.length} quer${queries.length===1?'y':'ies'} run</summary>`;
+    for (const q of queries) {
+      inner += `<pre>${esc(q.query)}</pre>`;
+      if (q.error) {
+        inner += `<div class="meta err">${esc(q.error)}</div>`;
+      } else {
+        inner += `<div class="meta">${q.row_count} row(s)${q.truncated ? ' (truncated)' : ''}</div>`;
+      }
+    }
+    det.innerHTML = inner;
+    bubble.appendChild(det);
+  }
+
+  function scroll() { document.getElementById('main').scrollTop = document.getElementById('main').scrollHeight; }
+
+  async function checkHealth() {
+    try {
+      const r = await fetch('/api/health');
+      const d = await r.json();
+      if (d.ready) {
+        statusEl.className = 'ok';
+        statusText.textContent = d.model || 'ready';
+      } else {
+        statusEl.className = 'bad';
+        statusText.textContent = d.error || 'not ready';
+      }
+    } catch {
+      statusEl.className = 'bad';
+      statusText.textContent = 'offline';
+    }
+  }
+
+  async function send(text) {
+    addMessage('user', text);
+    sendBtn.disabled = true;
+    const botMsg = addMessage('bot', '');
+    const bubble = botMsg.querySelector('.bubble');
+    bubble.innerHTML = '<span class="typing">Antern Bot is thinking…</span>';
+    try {
+      const r = await fetch('/api/chat', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ message: text, session_id: sessionId }),
+      });
+      const d = await r.json();
+      if (!r.ok) {
+        bubble.innerHTML = `<span class="typing">⚠ ${esc(d.error || 'Error')}</span>`;
+      } else {
+        sessionId = d.session_id;
+        bubble.textContent = d.answer || '(no answer)';
+        renderQueries(bubble, d.queries);
+      }
+    } catch (e) {
+      bubble.innerHTML = `<span class="typing">⚠ Network error: ${esc(e.message)}</span>`;
+    } finally {
+      sendBtn.disabled = false;
+      scroll();
+    }
+  }
+
+  form.addEventListener('submit', e => {
+    e.preventDefault();
+    const text = input.value.trim();
+    if (!text) return;
+    input.value = '';
+    input.style.height = 'auto';
+    send(text);
+  });
+
+  input.addEventListener('keydown', e => {
+    if (e.key === 'Enter' && !e.shiftKey) { e.preventDefault(); form.requestSubmit(); }
+  });
+  input.addEventListener('input', () => {
+    input.style.height = 'auto';
+    input.style.height = Math.min(input.scrollHeight, 160) + 'px';
+  });
+
+  resetBtn.addEventListener('click', async () => {
+    if (sessionId) {
+      try { await fetch('/api/reset', { method: 'POST', headers: {'Content-Type':'application/json'}, body: JSON.stringify({ session_id: sessionId }) }); } catch {}
+    }
+    sessionId = null;
+    messagesEl.innerHTML = '';
+    addMessage('bot', "Hi! I'm Antern Bot. Ask me anything about the recruitment data — candidates, requirements, applications, interviews, skills, and more.");
+  });
+
+  checkHealth();
+  addMessage('bot', "Hi! I'm Antern Bot. Ask me anything about the recruitment data — candidates, requirements, applications, interviews, skills, and more.");
+</script>
+</body>
+</html>

static/metrics.html

@@ -0,0 +1,153 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+<title>Antern Bot — Metrics</title>
+<style>
+  :root { --bg:#0f1115; --panel:#171a21; --panel2:#1f242e; --border:#2a303c; --text:#e8eaed; --muted:#9aa3b2; --accent:#4f8cff; --ok:#38d39f; --warn:#ffb020; --bad:#ff6b6b; }
+  * { box-sizing:border-box; }
+  body { margin:0; background:var(--bg); color:var(--text); font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif; padding:28px; }
+  h1 { font-size:22px; margin:0 0 4px; display:flex; align-items:center; gap:10px; }
+  h1 .logo { width:30px;height:30px;border-radius:8px;background:linear-gradient(135deg,#4f8cff,#8a5cff);display:flex;align-items:center;justify-content:center;font-weight:700; }
+  .sub { color:var(--muted); font-size:13px; margin-bottom:22px; }
+  .grid { display:grid; grid-template-columns:repeat(auto-fit,minmax(170px,1fr)); gap:14px; margin-bottom:26px; }
+  .card { background:var(--panel); border:1px solid var(--border); border-radius:12px; padding:16px 18px; }
+  .card .label { color:var(--muted); font-size:12px; text-transform:uppercase; letter-spacing:.04em; }
+  .card .value { font-size:26px; font-weight:700; margin-top:6px; }
+  .card .value.small { font-size:20px; }
+  h2 { font-size:15px; color:var(--muted); margin:24px 0 10px; font-weight:600; }
+  table { width:100%; border-collapse:collapse; background:var(--panel); border:1px solid var(--border); border-radius:12px; overflow:hidden; }
+  th,td { padding:10px 14px; text-align:left; border-bottom:1px solid var(--border); font-size:13.5px; }
+  th { background:var(--panel2); color:var(--muted); font-weight:600; }
+  td.num,th.num { text-align:right; font-variant-numeric:tabular-nums; }
+  tr:last-child td { border-bottom:none; }
+  .bar { height:8px; background:var(--panel2); border-radius:5px; overflow:hidden; margin-top:8px; }
+  .bar > span { display:block; height:100%; background:var(--accent); }
+  .muted { color:var(--muted); }
+  .pill { display:inline-block; padding:2px 9px; border-radius:20px; font-size:12px; font-weight:600; }
+  .pill.ok { background:rgba(56,211,159,.15); color:var(--ok); }
+  .pill.bad { background:rgba(255,107,107,.15); color:var(--bad); }
+  #updated { color:var(--muted); font-size:12px; }
+  .err { background:var(--panel); border:1px solid var(--border); border-radius:12px; padding:20px; }
+  .err code { background:var(--panel2); padding:2px 6px; border-radius:5px; }
+  .empty { color:var(--muted); padding:14px; }
+</style>
+</head>
+<body>
+  <h1><span class="logo">A</span> Antern Bot — Live Metrics</h1>
+  <div class="sub">Auto-refreshing every 5s · <span id="updated">—</span></div>
+  <div id="content"><div class="empty">Loading…</div></div>
+
+<script>
+  const token = new URLSearchParams(location.search).get("token") || "";
+  const $ = (id) => document.getElementById(id);
+
+  function commas(n) { return (n ?? 0).toLocaleString("en-US"); }
+  function money(n) { return "$" + (n ?? 0).toFixed(4); }
+  function uptime(s) {
+    s = Math.floor(s || 0);
+    const h = Math.floor(s/3600), m = Math.floor((s%3600)/60), sec = s%60;
+    return (h?h+"h ":"") + (m?m+"m ":"") + sec + "s";
+  }
+  function esc(s){ return (s==null?"":String(s)).replace(/[&<>"]/g,c=>({"&":"&amp;","<":"&lt;",">":"&gt;",'"':"&quot;"}[c])); }
+
+  function render(d, recent) {
+    const errPill = d.errors > 0 ? `<span class="pill bad">${d.errors}</span>` : `<span class="pill ok">0</span>`;
+    const cards = [
+      ["Requests", commas(d.requests)],
+      ["Sessions", commas(d.sessions)],
+      ["Errors", errPill, true],
+      ["Total tokens", commas(d.tokens_total)],
+      ["Total cost", money(d.total_cost_usd)],
+      ["Avg latency", commas(Math.round(d.avg_latency_ms)) + " ms"],
+      ["Avg tokens / chat", commas(Math.round(d.avg_tokens_per_request))],
+      ["Avg cost / chat", money(d.avg_cost_per_request_usd)],
+      ["Uptime", uptime(d.uptime_seconds)],
+    ];
+    let html = '<div class="grid">';
+    for (const [label, value, raw] of cards) {
+      html += `<div class="card"><div class="label">${label}</div><div class="value ${String(value).length>10?'small':''}">${raw?value:esc(value)}</div></div>`;
+    }
+    html += '</div>';
+
+    // Reliability + pricing table
+    html += '<h2>Reliability & pricing</h2><table><tbody>';
+    html += `<tr><td>Error rate</td><td class="num">${((d.error_rate||0)*100).toFixed(1)}%</td></tr>`;
+    html += `<tr><td>Blocked queries (security)</td><td class="num">${commas(d.blocked_queries)}</td></tr>`;
+    html += `<tr><td>SQL errors</td><td class="num">${commas(d.sql_errors)}</td></tr>`;
+    html += `<tr><td>Price (input / output per 1M tokens)</td><td class="num">$${d.price_per_1m?.input} / $${d.price_per_1m?.output}</td></tr>`;
+    html += '</tbody></table>';
+
+    // System
+    const cpu = d.system?.cpu_pct ?? 0, ram = d.system?.ram_pct ?? 0;
+    html += '<h2>System</h2><table><tbody>';
+    html += `<tr><td style="width:140px">CPU</td><td>${cpu}%<div class="bar"><span style="width:${cpu}%"></span></div></td></tr>`;
+    html += `<tr><td>RAM</td><td>${ram}%<div class="bar"><span style="width:${ram}%"></span></div></td></tr>`;
+    html += '</tbody></table>';
+
+    // Top sessions / cost per customer
+    html += '<h2>Top sessions (cost per customer)</h2>';
+    const s = d.top_sessions || [];
+    if (!s.length) {
+      html += '<div class="empty">No sessions yet — ask a few questions in the chat, then refresh.</div>';
+    } else {
+      html += '<table><thead><tr><th>Session</th><th class="num">Chats</th><th class="num">Prompt</th><th class="num">Completion</th><th class="num">Total tokens</th><th class="num">Cost</th></tr></thead><tbody>';
+      for (const r of s) {
+        html += `<tr><td>${esc(r.session_id)}</td><td class="num">${commas(r.requests)}</td><td class="num">${commas(r.prompt)}</td><td class="num">${commas(r.completion)}</td><td class="num">${commas(r.total)}</td><td class="num">${money(r.cost_usd)}</td></tr>`;
+      }
+      html += '</tbody></table>';
+    }
+
+    // Recent chats (from the durable log)
+    html += '<h2>Recent chats</h2>';
+    if (!recent || !recent.length) {
+      html += '<div class="empty">No chats logged yet.</div>';
+    } else {
+      html += '<table><thead><tr><th>Time</th><th>Session</th><th>Question</th><th>Output</th><th class="num">Latency</th><th class="num">Tokens</th><th class="num">Cost</th><th>Status</th></tr></thead><tbody>';
+      for (const c of recent) {
+        const t = c.ts ? new Date(c.ts).toLocaleTimeString() : "";
+        const out = c.presentation || "text";
+        let status = '<span class="pill ok">ok</span>';
+        if (c.error) status = '<span class="pill bad">error</span>';
+        else if (c.security_events) status = '<span class="pill bad">blocked</span>';
+        else if (c.sql_errors) status = '<span class="pill" style="background:rgba(255,176,32,.15);color:var(--warn)">sql err</span>';
+        const q = (c.question || "");
+        const qShort = esc(q.slice(0, 60)) + (q.length > 60 ? "…" : "");
+        html += `<tr><td class="muted">${t}</td><td>${esc(c.session_id)}</td><td>${qShort}</td><td>${esc(out)}</td><td class="num">${commas(Math.round(c.latency_ms||0))} ms</td><td class="num">${commas(c.tokens||0)}</td><td class="num">${money(c.cost_usd||0)}</td><td>${status}</td></tr>`;
+      }
+      html += '</tbody></table>';
+    }
+
+    $("content").innerHTML = html;
+    $("updated").textContent = "updated " + new Date().toLocaleTimeString();
+  }
+
+  async function load() {
+    const H = { headers: { "ngrok-skip-browser-warning": "true" } };
+    const q = token ? ("?token=" + encodeURIComponent(token)) : "";
+    try {
+      const r = await fetch("/api/metrics" + q, H);
+      if (r.status === 401) {
+        $("content").innerHTML = '<div class="err">🔒 <b>Unauthorized.</b> Add your metrics token to the URL:<br><br><code>'
+          + location.pathname + '?token=YOUR_TOKEN</code></div>';
+        return;
+      }
+      const d = await r.json();
+      let recent = [];
+      try {
+        const rUrl = "/api/metrics/recent?limit=20" + (token ? ("&token=" + encodeURIComponent(token)) : "");
+        const rr = await fetch(rUrl, H);
+        if (rr.ok) recent = (await rr.json()).recent || [];
+      } catch (e) { /* recent is best-effort */ }
+      render(d, recent);
+    } catch (e) {
+      $("content").innerHTML = '<div class="err">⚠ Cannot reach the server. Is the bot running on this host?</div>';
+    }
+  }
+
+  load();
+  setInterval(load, 5000);
+</script>
+</body>
+</html>

static/preview.html

@@ -0,0 +1,269 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+<title>Embed preview — your website</title>
+<style>
+  body { font-family: Georgia, "Times New Roman", serif; margin: 0; color: #1f2430; background: #f6f4ee; }
+  .topbar { background: #fff; border-bottom: 1px solid #e7e3d8; padding: 16px 32px; font-weight: 700; font-size: 20px; }
+  .hero { max-width: 780px; margin: 0 auto; padding: 70px 24px; }
+  h1 { font-size: 40px; line-height: 1.15; margin: 0 0 18px; }
+  p { font-size: 18px; line-height: 1.75; color: #444; }
+  .card { background: #fff; border: 1px solid #e7e3d8; border-radius: 12px; padding: 18px 22px; margin-top: 32px; font-size: 15px; font-family: -apple-system, "Segoe UI", sans-serif; }
+  .card b { color: #1f2430; }
+</style>
+</head>
+<body>
+  <div class="topbar">Antern&nbsp;Tech</div>
+  <div class="hero">
+    <h1>This is a preview of your website with the bot embedded.</h1>
+    <p>Pretend this page is one of your real web pages. The only thing added is the
+       inline embed snippet (the same one in <code>embed-inline.html</code>). Look
+       at the bottom-right corner — there's a chat button. Click it and ask a
+       question; it talks to your live bot over the public URL. The footer inside
+       the chat window shows today's chat count, average cost, and last chat's tokens.</p>
+    <div class="card">
+      <b>Try (table):</b> "List candidates with their designation and experience." &nbsp;·&nbsp;
+      <b>(bar chart):</b> "Top 5 designations by number of candidates." &nbsp;·&nbsp;
+      <b>(pie chart):</b> "Break down requirements by status." &nbsp;·&nbsp;
+      <b>(text):</b> "How many active candidates are there?"
+    </div>
+  </div>
+
+  <!-- ===== Antern Bot inline embed (points at the public ngrok URL) ===== -->
+  <script>
+  (function () {
+    var API = "https://duckling-bovine-blitz.ngrok-free.dev";
+    var TITLE = "Antern Bot";
+    var ACCENT = "#4f8cff";
+    var GREETING = "👋 Hi! I'm Antern Bot, your data assistant.\n\nAsk me anything about your recruitment data — candidates, requirements, applications, interviews — in plain English.\n\nTry: “How many active candidates do we have?”";
+    var STORAGE_KEY = "antern_bot_session";
+    API = API.replace(/\/$/, "");
+
+    var host = document.createElement("div");
+    host.id = "antern-bot-widget";
+    document.body.appendChild(host);
+    var root = host.attachShadow({ mode: "open" });
+
+    root.innerHTML =
+      '<style>' +
+      ':host{all:initial;}' +
+      '*{box-sizing:border-box;font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif;}' +
+      '.launcher{position:fixed;bottom:24px;right:24px;width:62px;height:62px;border-radius:50%;border:none;cursor:pointer;background:linear-gradient(135deg,' + ACCENT + ',#8a5cff);color:#fff;z-index:2147483000;display:flex;align-items:center;justify-content:center;box-shadow:0 10px 28px rgba(0,0,0,.30),0 4px 12px rgba(79,140,255,.45);transition:transform .25s cubic-bezier(.2,.9,.3,1.2),box-shadow .25s;animation:antern-pop .5s cubic-bezier(.2,.9,.3,1.2);}' +
+      '.launcher::after{content:"";position:absolute;inset:0;border-radius:50%;background:linear-gradient(135deg,' + ACCENT + ',#8a5cff);z-index:-1;animation:antern-pulse 2.6s ease-out infinite;}' +
+      '.launcher.open::after{animation:none;opacity:0;}' +
+      '.launcher:hover{transform:translateY(-3px) scale(1.05);box-shadow:0 16px 38px rgba(0,0,0,.34),0 6px 18px rgba(79,140,255,.55);}' +
+      '.launcher:active{transform:translateY(-1px) scale(.97);}' +
+      '.launcher svg{width:27px;height:27px;}' +
+      '.launcher .ic-close{display:none;}' +
+      '.launcher.open .ic-chat{display:none;}' +
+      '.launcher.open .ic-close{display:block;}' +
+      '@keyframes antern-pop{0%{transform:scale(0) rotate(-25deg);}100%{transform:scale(1) rotate(0);}}' +
+      '@keyframes antern-pulse{0%{transform:scale(1);opacity:.45;}70%{transform:scale(1.7);opacity:0;}100%{opacity:0;}}' +
+      '.panel{position:fixed;bottom:92px;right:22px;width:760px;max-width:calc(100vw - 32px);height:1120px;max-height:calc(100vh - 120px);background:#0f1115;border:1px solid #2a303c;border-radius:16px;box-shadow:0 12px 40px rgba(0,0,0,.4);z-index:2147483000;display:none;flex-direction:column;overflow:hidden;}' +
+      '.panel.open{display:flex;}' +
+      '.head{background:#171a21;border-bottom:1px solid #2a303c;padding:13px 16px;display:flex;align-items:center;gap:10px;color:#e8eaed;}' +
+      '.head .badge{width:28px;height:28px;border-radius:8px;background:' + ACCENT + ';display:flex;align-items:center;justify-content:center;font-weight:700;}' +
+      '.head h3{margin:0;font-size:15px;flex:1;}' +
+      '.head button{background:none;border:none;color:#9aa3b2;cursor:pointer;font-size:20px;line-height:1;}' +
+      '.body{flex:1;overflow-y:auto;padding:16px;background:#0f1115;}' +
+      '.msg{display:flex;gap:9px;margin-bottom:14px;}' +
+      '.msg .av{width:26px;height:26px;border-radius:7px;flex-shrink:0;display:flex;align-items:center;justify-content:center;font-size:11px;font-weight:700;color:#fff;}' +
+      '.msg.bot .av{background:' + ACCENT + ';}' +
+      '.msg.user .av{background:#374151;}' +
+      '.bubble{background:#232936;border:1px solid #2a303c;border-radius:11px;padding:10px 13px;color:#e8eaed;font-size:14px;line-height:1.5;white-space:pre-wrap;word-wrap:break-word;max-width:100%;}' +
+      '.msg.user .bubble{background:#1f242e;}' +
+      '.typing{color:#9aa3b2;font-style:italic;}' +
+      '.foot{border-top:1px solid #2a303c;background:#171a21;padding:11px;display:flex;gap:8px;}' +
+      '.foot textarea{flex:1;resize:none;background:#1f242e;color:#e8eaed;border:1px solid #2a303c;border-radius:9px;padding:9px 11px;font-size:14px;max-height:120px;}' +
+      '.foot textarea:focus{outline:none;border-color:' + ACCENT + ';}' +
+      '.foot button{background:' + ACCENT + ';color:#fff;border:none;border-radius:9px;padding:0 16px;font-weight:600;cursor:pointer;font-size:14px;}' +
+      '.foot button:disabled{opacity:.5;cursor:not-allowed;}' +
+      '.cap{font-size:11.5px;color:#9aa3b2;margin:10px 0 4px;}' +
+      '.tbl-wrap{margin-top:8px;max-height:260px;overflow:auto;border:1px solid #2a303c;border-radius:9px;}' +
+      'table.tbl{border-collapse:collapse;width:100%;font-size:12.5px;}' +
+      'table.tbl th,table.tbl td{padding:6px 9px;border-bottom:1px solid #2a303c;text-align:left;white-space:nowrap;}' +
+      'table.tbl th{position:sticky;top:0;background:#1f242e;color:#cbd5e1;font-weight:600;}' +
+      'table.tbl td{color:#e8eaed;}' +
+      'table.tbl tr:hover td{background:#1a1f29;}' +
+      '.chart-wrap{margin-top:8px;background:#fff;border-radius:9px;padding:10px;}' +
+      '.chart-wrap canvas{max-width:100%;}' +
+      '.stats{padding:7px 12px;background:#12151b;border-top:1px solid #2a303c;color:#9aa3b2;font-size:11px;text-align:center;}' +
+      '</style>' +
+      '<button class="launcher" aria-label="Open chat">' +
+      '<svg class="ic-chat" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M21 11.5a8.5 8.5 0 0 1-12.5 7.48L3 21l2.02-5.5A8.5 8.5 0 1 1 21 11.5z"/><circle cx="8.5" cy="11.5" r="1" fill="currentColor" stroke="none"/><circle cx="12" cy="11.5" r="1" fill="currentColor" stroke="none"/><circle cx="15.5" cy="11.5" r="1" fill="currentColor" stroke="none"/></svg>' +
+      '<svg class="ic-close" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.4" stroke-linecap="round" stroke-linejoin="round"><path d="M6 9l6 6 6-6"/></svg>' +
+      '</button>' +
+      '<div class="panel" role="dialog" aria-label="' + TITLE + '">' +
+      '  <div class="head"><div class="badge">A</div><h3>' + TITLE + '</h3><button class="close" aria-label="Close">×</button></div>' +
+      '  <div class="body"></div>' +
+      '  <div class="foot"><textarea rows="1" placeholder="Type your question…"></textarea><button class="send">Send</button></div>' +
+      '  <div class="stats"></div>' +
+      '</div>';
+
+    var launcher = root.querySelector(".launcher");
+    var panel = root.querySelector(".panel");
+    var closeBtn = root.querySelector(".close");
+    var body = root.querySelector(".body");
+    var input = root.querySelector("textarea");
+    var sendBtn = root.querySelector(".send");
+    var statsEl = root.querySelector(".stats");
+    var sessionId = localStorage.getItem(STORAGE_KEY) || null;
+    var greeted = false;
+    var PALETTE = ["#4f8cff","#8a5cff","#38d39f","#ffb020","#ff6b6b","#22b8cf","#f783ac","#a0d911"];
+    var chartJsPromise = null;
+
+    function loadChartJs() {
+      if (window.Chart) return Promise.resolve(window.Chart);
+      if (chartJsPromise) return chartJsPromise;
+      chartJsPromise = new Promise(function (resolve, reject) {
+        var s = document.createElement("script");
+        s.src = "https://cdn.jsdelivr.net/npm/chart.js@4/dist/chart.umd.min.js";
+        s.onload = function () { resolve(window.Chart); };
+        s.onerror = function () { reject(new Error("chart lib failed")); };
+        document.head.appendChild(s);
+      });
+      return chartJsPromise;
+    }
+
+    function renderTable(container, p) {
+      var cols = p.columns || [], rows = p.rows || [];
+      if (p.title) { var c = document.createElement("div"); c.className = "cap"; c.textContent = p.title; container.appendChild(c); }
+      var wrap = document.createElement("div"); wrap.className = "tbl-wrap";
+      var t = document.createElement("table"); t.className = "tbl";
+      var thead = document.createElement("thead"), trh = document.createElement("tr");
+      cols.forEach(function (col) { var th = document.createElement("th"); th.textContent = col; trh.appendChild(th); });
+      thead.appendChild(trh); t.appendChild(thead);
+      var tb = document.createElement("tbody");
+      rows.forEach(function (r) {
+        var tr = document.createElement("tr");
+        r.forEach(function (v) { var td = document.createElement("td"); td.textContent = (v === null || v === undefined) ? "" : v; tr.appendChild(td); });
+        tb.appendChild(tr);
+      });
+      t.appendChild(tb); wrap.appendChild(t); container.appendChild(wrap);
+      if (p.truncated) { var n = document.createElement("div"); n.className = "cap"; n.textContent = "(showing first " + rows.length + " rows)"; container.appendChild(n); }
+    }
+
+    function renderChart(container, p) {
+      var cols = p.columns || [], rows = p.rows || [];
+      var xi = cols.indexOf(p.x_field);
+      var yIdx = (p.y_fields || []).map(function (f) { return cols.indexOf(f); }).filter(function (i) { return i >= 0; });
+      if (xi < 0 || yIdx.length === 0) { renderTable(container, p); return; }
+      if (p.title) { var cap = document.createElement("div"); cap.className = "cap"; cap.textContent = p.title; container.appendChild(cap); }
+      var wrap = document.createElement("div"); wrap.className = "chart-wrap";
+      var canvas = document.createElement("canvas"); wrap.appendChild(canvas); container.appendChild(wrap);
+      var labels = rows.map(function (r) { return r[xi]; });
+      loadChartJs().then(function (Chart) {
+        if (p.format === "pie") {
+          var fi = yIdx[0];
+          new Chart(canvas, {
+            type: "pie",
+            data: { labels: labels, datasets: [{ data: rows.map(function (r) { return Number(r[fi]) || 0; }), backgroundColor: labels.map(function (_, i) { return PALETTE[i % PALETTE.length]; }) }] },
+            options: { responsive: true, plugins: { legend: { position: "right" } } },
+          });
+        } else {
+          var datasets = yIdx.map(function (ci, k) {
+            return { label: cols[ci], data: rows.map(function (r) { return Number(r[ci]) || 0; }), backgroundColor: PALETTE[k % PALETTE.length], borderColor: PALETTE[k % PALETTE.length], fill: false, tension: 0.25 };
+          });
+          new Chart(canvas, {
+            type: p.format === "line" ? "line" : "bar",
+            data: { labels: labels, datasets: datasets },
+            options: { responsive: true, plugins: { legend: { display: yIdx.length > 1 } }, scales: { y: { beginAtZero: true } } },
+          });
+        }
+        body.scrollTop = body.scrollHeight;
+      }).catch(function () {
+        var e = document.createElement("div"); e.className = "cap"; e.textContent = "(couldn't load chart — showing table)"; container.appendChild(e);
+        renderTable(container, p);
+      });
+    }
+
+    function renderPresentation(bubble, p) {
+      if (!p || !p.format || p.format === "text") return;
+      var box = document.createElement("div");
+      bubble.appendChild(box);
+      if (p.format === "table") renderTable(box, p);
+      else renderChart(box, p);
+    }
+
+    var STATS_KEY = "antern_bot_daystats";
+    var lastTokens = null;
+    function _today() { return new Date().toISOString().slice(0, 10); }
+    function getStats() {
+      var s;
+      try { s = JSON.parse(localStorage.getItem(STATS_KEY) || "{}"); } catch (e) { s = {}; }
+      if (s.date !== _today()) s = { date: _today(), chats: 0, cost: 0 };
+      return s;
+    }
+    function bumpStats(cost) {
+      var s = getStats();
+      s.chats += 1; s.cost += (cost || 0);
+      localStorage.setItem(STATS_KEY, JSON.stringify(s));
+    }
+    function renderStats() {
+      var s = getStats();
+      var avg = s.chats ? s.cost / s.chats : 0;
+      var parts = ["Today: " + s.chats + " chat" + (s.chats === 1 ? "" : "s"),
+                   "avg $" + avg.toFixed(4) + "/chat"];
+      if (lastTokens != null) parts.push("last: " + lastTokens.toLocaleString() + " tokens");
+      statsEl.textContent = parts.join("  ·  ");
+    }
+
+    function esc(s) {
+      return (s == null ? "" : String(s)).replace(/[&<>"]/g, function (c) {
+        return { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" }[c];
+      });
+    }
+
+    function addMsg(role, text) {
+      var m = document.createElement("div");
+      m.className = "msg " + role;
+      m.innerHTML = '<div class="av">' + (role === "user" ? "You" : "A") + "</div><div class=\"bubble\"></div>";
+      m.querySelector(".bubble").textContent = text;
+      body.appendChild(m); body.scrollTop = body.scrollHeight; return m;
+    }
+
+    function setOpen(open) {
+      panel.classList.toggle("open", open);
+      launcher.classList.toggle("open", open);
+      launcher.setAttribute("aria-label", open ? "Close chat" : "Open chat");
+      if (open && !greeted) { addMsg("bot", GREETING); greeted = true; }
+      if (open) { renderStats(); input.focus(); }
+    }
+
+    async function send(text) {
+      addMsg("user", text); sendBtn.disabled = true;
+      var m = addMsg("bot", ""); var bubble = m.querySelector(".bubble");
+      bubble.innerHTML = '<span class="typing">Thinking…</span>';
+      try {
+        var r = await fetch(API + "/api/chat", {
+          method: "POST",
+          headers: { "Content-Type": "application/json", "ngrok-skip-browser-warning": "true" },
+          body: JSON.stringify({ message: text, session_id: sessionId }),
+        });
+        var d = await r.json();
+        if (!r.ok) { bubble.innerHTML = '<span class="typing">⚠ ' + esc(d.error || "Error") + "</span>"; }
+        else {
+          sessionId = d.session_id; localStorage.setItem(STORAGE_KEY, sessionId);
+          bubble.textContent = d.answer || "(no answer)";
+          renderPresentation(bubble, d.presentation);
+          if (typeof d.cost_usd === "number") bumpStats(d.cost_usd);
+          if (typeof d.tokens === "number") lastTokens = d.tokens;
+          renderStats();
+        }
+      } catch (e) { bubble.innerHTML = '<span class="typing">⚠ Network error</span>'; }
+      finally { sendBtn.disabled = false; body.scrollTop = body.scrollHeight; }
+    }
+    function submit() { var t = input.value.trim(); if (!t) return; input.value = ""; input.style.height = "auto"; send(t); }
+    launcher.addEventListener("click", function () { setOpen(!panel.classList.contains("open")); });
+    closeBtn.addEventListener("click", function () { setOpen(false); });
+    sendBtn.addEventListener("click", submit);
+    input.addEventListener("keydown", function (e) { if (e.key === "Enter" && !e.shiftKey) { e.preventDefault(); submit(); } });
+    input.addEventListener("input", function () { input.style.height = "auto"; input.style.height = Math.min(input.scrollHeight, 120) + "px"; });
+
+    renderStats();
+  })();
+  </script>
+</body>
+</html>

static/widget.js

@@ -0,0 +1,285 @@
+/* Antern Bot embeddable chat widget.
+ *
+ * Add to any page:
+ *   <script src="https://YOUR_BOT_HOST/static/widget.js"
+ *           data-api="https://YOUR_BOT_HOST"
+ *           data-title="Antern Bot"
+ *           data-accent="#4f8cff"
+ *           data-greeting="Hi! Ask me anything about your data."></script>
+ *
+ * The widget renders a floating button + chat panel. It calls
+ * `${data-api}/api/chat` and keeps a session id in localStorage.
+ */
+(function () {
+  var script = document.currentScript;
+  // data-api is the bot's base URL. Empty/omitted => same origin as this page
+  // (only works when the page is served by the bot itself, e.g. the demo).
+  var API = (script.getAttribute("data-api") || "").replace(/\/$/, "");
+  var TITLE = script.getAttribute("data-title") || "Antern Bot";
+  var ACCENT = script.getAttribute("data-accent") || "#4f8cff";
+  var GREETING =
+    script.getAttribute("data-greeting") ||
+    "👋 Hi! I'm Antern Bot, your data assistant.\n\nAsk me anything about your recruitment data — candidates, requirements, applications, interviews — in plain English.\n\nTry: “How many active candidates do we have?”";
+  var STORAGE_KEY = "antern_bot_session";
+
+  if (!script.hasAttribute("data-api")) {
+    console.warn(
+      "[antern-bot] No data-api attribute set; calling same origin. " +
+      "When embedding on another site, set data-api to your bot's URL."
+    );
+  }
+
+  // --- Host element + shadow root (style isolation) ---
+  var host = document.createElement("div");
+  host.id = "antern-bot-widget";
+  document.body.appendChild(host);
+  var root = host.attachShadow({ mode: "open" });
+
+  root.innerHTML =
+    '<style>' +
+    ':host{all:initial;}' +
+    '*{box-sizing:border-box;font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif;}' +
+    '.launcher{position:fixed;bottom:24px;right:24px;width:62px;height:62px;border-radius:50%;border:none;cursor:pointer;background:linear-gradient(135deg,' + ACCENT + ',#8a5cff);color:#fff;z-index:2147483000;display:flex;align-items:center;justify-content:center;box-shadow:0 10px 28px rgba(0,0,0,.30),0 4px 12px rgba(79,140,255,.45);transition:transform .25s cubic-bezier(.2,.9,.3,1.2),box-shadow .25s;animation:antern-pop .5s cubic-bezier(.2,.9,.3,1.2);}' +
+    '.launcher::after{content:"";position:absolute;inset:0;border-radius:50%;background:linear-gradient(135deg,' + ACCENT + ',#8a5cff);z-index:-1;animation:antern-pulse 2.6s ease-out infinite;}' +
+    '.launcher.open::after{animation:none;opacity:0;}' +
+    '.launcher:hover{transform:translateY(-3px) scale(1.05);box-shadow:0 16px 38px rgba(0,0,0,.34),0 6px 18px rgba(79,140,255,.55);}' +
+    '.launcher:active{transform:translateY(-1px) scale(.97);}' +
+    '.launcher svg{width:27px;height:27px;}' +
+    '.launcher .ic-close{display:none;}' +
+    '.launcher.open .ic-chat{display:none;}' +
+    '.launcher.open .ic-close{display:block;}' +
+    '@keyframes antern-pop{0%{transform:scale(0) rotate(-25deg);}100%{transform:scale(1) rotate(0);}}' +
+    '@keyframes antern-pulse{0%{transform:scale(1);opacity:.45;}70%{transform:scale(1.7);opacity:0;}100%{opacity:0;}}' +
+    '.panel{position:fixed;bottom:92px;right:22px;width:760px;max-width:calc(100vw - 32px);height:1120px;max-height:calc(100vh - 120px);background:#0f1115;border:1px solid #2a303c;border-radius:16px;box-shadow:0 12px 40px rgba(0,0,0,.4);z-index:2147483000;display:none;flex-direction:column;overflow:hidden;}' +
+    '.panel.open{display:flex;}' +
+    '.head{background:#171a21;border-bottom:1px solid #2a303c;padding:13px 16px;display:flex;align-items:center;gap:10px;color:#e8eaed;}' +
+    '.head .badge{width:28px;height:28px;border-radius:8px;background:' + ACCENT + ';display:flex;align-items:center;justify-content:center;font-weight:700;}' +
+    '.head h3{margin:0;font-size:15px;flex:1;}' +
+    '.head button{background:none;border:none;color:#9aa3b2;cursor:pointer;font-size:20px;line-height:1;}' +
+    '.body{flex:1;overflow-y:auto;padding:16px;background:#0f1115;}' +
+    '.msg{display:flex;gap:9px;margin-bottom:14px;}' +
+    '.msg .av{width:26px;height:26px;border-radius:7px;flex-shrink:0;display:flex;align-items:center;justify-content:center;font-size:11px;font-weight:700;color:#fff;}' +
+    '.msg.bot .av{background:' + ACCENT + ';}' +
+    '.msg.user .av{background:#374151;}' +
+    '.bubble{background:#232936;border:1px solid #2a303c;border-radius:11px;padding:10px 13px;color:#e8eaed;font-size:14px;line-height:1.5;white-space:pre-wrap;word-wrap:break-word;max-width:100%;}' +
+    '.msg.user .bubble{background:#1f242e;}' +
+    '.typing{color:#9aa3b2;font-style:italic;}' +
+    '.foot{border-top:1px solid #2a303c;background:#171a21;padding:11px;display:flex;gap:8px;}' +
+    '.foot textarea{flex:1;resize:none;background:#1f242e;color:#e8eaed;border:1px solid #2a303c;border-radius:9px;padding:9px 11px;font-size:14px;max-height:120px;}' +
+    '.foot textarea:focus{outline:none;border-color:' + ACCENT + ';}' +
+    '.foot button{background:' + ACCENT + ';color:#fff;border:none;border-radius:9px;padding:0 16px;font-weight:600;cursor:pointer;font-size:14px;}' +
+    '.foot button:disabled{opacity:.5;cursor:not-allowed;}' +
+    '.cap{font-size:11.5px;color:#9aa3b2;margin:10px 0 4px;}' +
+    '.tbl-wrap{margin-top:8px;max-height:260px;overflow:auto;border:1px solid #2a303c;border-radius:9px;}' +
+    'table.tbl{border-collapse:collapse;width:100%;font-size:12.5px;}' +
+    'table.tbl th,table.tbl td{padding:6px 9px;border-bottom:1px solid #2a303c;text-align:left;white-space:nowrap;}' +
+    'table.tbl th{position:sticky;top:0;background:#1f242e;color:#cbd5e1;font-weight:600;}' +
+    'table.tbl td{color:#e8eaed;}' +
+    'table.tbl tr:hover td{background:#1a1f29;}' +
+    '.chart-wrap{margin-top:8px;background:#fff;border-radius:9px;padding:10px;}' +
+    '.chart-wrap canvas{max-width:100%;}' +
+    '.stats{padding:7px 12px;background:#12151b;border-top:1px solid #2a303c;color:#9aa3b2;font-size:11px;text-align:center;}' +
+    '</style>' +
+    '<button class="launcher" aria-label="Open chat">' +
+    '<svg class="ic-chat" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M21 11.5a8.5 8.5 0 0 1-12.5 7.48L3 21l2.02-5.5A8.5 8.5 0 1 1 21 11.5z"/><circle cx="8.5" cy="11.5" r="1" fill="currentColor" stroke="none"/><circle cx="12" cy="11.5" r="1" fill="currentColor" stroke="none"/><circle cx="15.5" cy="11.5" r="1" fill="currentColor" stroke="none"/></svg>' +
+    '<svg class="ic-close" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.4" stroke-linecap="round" stroke-linejoin="round"><path d="M6 9l6 6 6-6"/></svg>' +
+    '</button>' +
+    '<div class="panel" role="dialog" aria-label="' + TITLE + '">' +
+    '  <div class="head"><div class="badge">A</div><h3>' + TITLE + '</h3><button class="close" aria-label="Close">×</button></div>' +
+    '  <div class="body"></div>' +
+    '  <div class="foot"><textarea rows="1" placeholder="Type your question…"></textarea><button class="send">Send</button></div>' +
+    '  <div class="stats"></div>' +
+    '</div>';
+
+  var launcher = root.querySelector(".launcher");
+  var panel = root.querySelector(".panel");
+  var closeBtn = root.querySelector(".close");
+  var body = root.querySelector(".body");
+  var input = root.querySelector("textarea");
+  var sendBtn = root.querySelector(".send");
+  var statsEl = root.querySelector(".stats");
+  var sessionId = localStorage.getItem(STORAGE_KEY) || null;
+  var greeted = false;
+  var PALETTE = ["#4f8cff","#8a5cff","#38d39f","#ffb020","#ff6b6b","#22b8cf","#f783ac","#a0d911"];
+  var chartJsPromise = null;
+
+  function loadChartJs() {
+    if (window.Chart) return Promise.resolve(window.Chart);
+    if (chartJsPromise) return chartJsPromise;
+    chartJsPromise = new Promise(function (resolve, reject) {
+      var s = document.createElement("script");
+      s.src = "https://cdn.jsdelivr.net/npm/chart.js@4/dist/chart.umd.min.js";
+      s.onload = function () { resolve(window.Chart); };
+      s.onerror = function () { reject(new Error("chart lib failed")); };
+      document.head.appendChild(s);
+    });
+    return chartJsPromise;
+  }
+
+  function renderTable(container, p) {
+    var cols = p.columns || [], rows = p.rows || [];
+    if (p.title) { var c = document.createElement("div"); c.className = "cap"; c.textContent = p.title; container.appendChild(c); }
+    var wrap = document.createElement("div"); wrap.className = "tbl-wrap";
+    var t = document.createElement("table"); t.className = "tbl";
+    var thead = document.createElement("thead"), trh = document.createElement("tr");
+    cols.forEach(function (col) { var th = document.createElement("th"); th.textContent = col; trh.appendChild(th); });
+    thead.appendChild(trh); t.appendChild(thead);
+    var tb = document.createElement("tbody");
+    rows.forEach(function (r) {
+      var tr = document.createElement("tr");
+      r.forEach(function (v) { var td = document.createElement("td"); td.textContent = (v === null || v === undefined) ? "" : v; tr.appendChild(td); });
+      tb.appendChild(tr);
+    });
+    t.appendChild(tb); wrap.appendChild(t); container.appendChild(wrap);
+    if (p.truncated) { var n = document.createElement("div"); n.className = "cap"; n.textContent = "(showing first " + rows.length + " rows)"; container.appendChild(n); }
+  }
+
+  function renderChart(container, p) {
+    var cols = p.columns || [], rows = p.rows || [];
+    var xi = cols.indexOf(p.x_field);
+    var yIdx = (p.y_fields || []).map(function (f) { return cols.indexOf(f); }).filter(function (i) { return i >= 0; });
+    if (xi < 0 || yIdx.length === 0) { renderTable(container, p); return; }  // fall back
+    if (p.title) { var cap = document.createElement("div"); cap.className = "cap"; cap.textContent = p.title; container.appendChild(cap); }
+    var wrap = document.createElement("div"); wrap.className = "chart-wrap";
+    var canvas = document.createElement("canvas"); wrap.appendChild(canvas); container.appendChild(wrap);
+    var labels = rows.map(function (r) { return r[xi]; });
+    loadChartJs().then(function (Chart) {
+      if (p.format === "pie") {
+        var fi = yIdx[0];
+        new Chart(canvas, {
+          type: "pie",
+          data: { labels: labels, datasets: [{ data: rows.map(function (r) { return Number(r[fi]) || 0; }), backgroundColor: labels.map(function (_, i) { return PALETTE[i % PALETTE.length]; }) }] },
+          options: { responsive: true, plugins: { legend: { position: "right" } } },
+        });
+      } else {
+        var datasets = yIdx.map(function (ci, k) {
+          return { label: cols[ci], data: rows.map(function (r) { return Number(r[ci]) || 0; }), backgroundColor: PALETTE[k % PALETTE.length], borderColor: PALETTE[k % PALETTE.length], fill: false, tension: 0.25 };
+        });
+        new Chart(canvas, {
+          type: p.format === "line" ? "line" : "bar",
+          data: { labels: labels, datasets: datasets },
+          options: { responsive: true, plugins: { legend: { display: yIdx.length > 1 } }, scales: { y: { beginAtZero: true } } },
+        });
+      }
+      body.scrollTop = body.scrollHeight;
+    }).catch(function () {
+      var e = document.createElement("div"); e.className = "cap"; e.textContent = "(couldn't load chart — showing table)"; container.appendChild(e);
+      renderTable(container, p);
+    });
+  }
+
+  function renderPresentation(bubble, p) {
+    if (!p || !p.format || p.format === "text") return;
+    var box = document.createElement("div");
+    bubble.appendChild(box);
+    if (p.format === "table") renderTable(box, p);
+    else renderChart(box, p);
+  }
+
+  var STATS_KEY = "antern_bot_daystats";
+  var lastTokens = null;
+  function _today() { return new Date().toISOString().slice(0, 10); }
+  function getStats() {
+    var s;
+    try { s = JSON.parse(localStorage.getItem(STATS_KEY) || "{}"); } catch (e) { s = {}; }
+    if (s.date !== _today()) s = { date: _today(), chats: 0, cost: 0 };
+    return s;
+  }
+  function bumpStats(cost) {
+    var s = getStats();
+    s.chats += 1; s.cost += (cost || 0);
+    localStorage.setItem(STATS_KEY, JSON.stringify(s));
+  }
+  function renderStats() {
+    var s = getStats();
+    var avg = s.chats ? s.cost / s.chats : 0;
+    var parts = ["Today: " + s.chats + " chat" + (s.chats === 1 ? "" : "s"),
+                 "avg $" + avg.toFixed(4) + "/chat"];
+    if (lastTokens != null) parts.push("last: " + lastTokens.toLocaleString() + " tokens");
+    statsEl.textContent = parts.join("  ·  ");
+  }
+
+  function esc(s) {
+    return (s == null ? "" : String(s)).replace(/[&<>"]/g, function (c) {
+      return { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" }[c];
+    });
+  }
+
+  function addMsg(role, text) {
+    var m = document.createElement("div");
+    m.className = "msg " + role;
+    m.innerHTML =
+      '<div class="av">' + (role === "user" ? "You" : "A") + "</div>" +
+      '<div class="bubble"></div>';
+    m.querySelector(".bubble").textContent = text;
+    body.appendChild(m);
+    body.scrollTop = body.scrollHeight;
+    return m;
+  }
+
+  function setOpen(open) {
+    panel.classList.toggle("open", open);
+    launcher.classList.toggle("open", open);
+    launcher.setAttribute("aria-label", open ? "Close chat" : "Open chat");
+    if (open && !greeted) { addMsg("bot", GREETING); greeted = true; }
+    if (open) { renderStats(); input.focus(); }
+  }
+
+  async function send(text) {
+    addMsg("user", text);
+    sendBtn.disabled = true;
+    var m = addMsg("bot", "");
+    var bubble = m.querySelector(".bubble");
+    bubble.innerHTML = '<span class="typing">Thinking…</span>';
+    try {
+      var r = await fetch(API + "/api/chat", {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          // Skip ngrok's free-tier browser-warning interstitial on API calls.
+          // Harmless on other hosts.
+          "ngrok-skip-browser-warning": "true",
+        },
+        body: JSON.stringify({ message: text, session_id: sessionId }),
+      });
+      var d = await r.json();
+      if (!r.ok) {
+        bubble.innerHTML = '<span class="typing">⚠ ' + esc(d.error || "Error") + "</span>";
+      } else {
+        sessionId = d.session_id;
+        localStorage.setItem(STORAGE_KEY, sessionId);
+        bubble.textContent = d.answer || "(no answer)";
+        renderPresentation(bubble, d.presentation);
+        if (typeof d.cost_usd === "number") bumpStats(d.cost_usd);
+        if (typeof d.tokens === "number") lastTokens = d.tokens;
+        renderStats();
+      }
+    } catch (e) {
+      bubble.innerHTML = '<span class="typing">⚠ Network error</span>';
+    } finally {
+      sendBtn.disabled = false;
+      body.scrollTop = body.scrollHeight;
+    }
+  }
+
+  function submit() {
+    var t = input.value.trim();
+    if (!t) return;
+    input.value = "";
+    input.style.height = "auto";
+    send(t);
+  }
+
+  launcher.addEventListener("click", function () { setOpen(!panel.classList.contains("open")); });
+  closeBtn.addEventListener("click", function () { setOpen(false); });
+  sendBtn.addEventListener("click", submit);
+  input.addEventListener("keydown", function (e) {
+    if (e.key === "Enter" && !e.shiftKey) { e.preventDefault(); submit(); }
+  });
+  input.addEventListener("input", function () {
+    input.style.height = "auto";
+    input.style.height = Math.min(input.scrollHeight, 120) + "px";
+  });
+
+  renderStats();
+})();