Upload folder using huggingface_hub

.gitattributes

@@ -33,3 +33,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+demo_dbs/world_1/world_1.sqlite filter=lfs diff=lfs merge=lfs -text

Dockerfile

@@ -0,0 +1,26 @@
+# Minimal CPU image for the Hugging Face Space (no CUDA, no training deps).
+FROM python:3.11-slim
+
+# CPU-only torch — keeps the image small (no multi-GB CUDA wheels)
+RUN pip install --no-cache-dir torch --index-url https://download.pytorch.org/whl/cpu
+
+WORKDIR /app
+COPY requirements-serve.txt .
+RUN pip install --no-cache-dir -r requirements-serve.txt
+
+# non-root user (HF Spaces convention) with a writable home for the HF model cache
+RUN useradd -m -u 1000 user
+COPY --chown=user . /app
+USER user
+
+ENV HOME=/home/user \
+    PATH=/home/user/.local/bin:$PATH \
+    HF_HOME=/home/user/.cache/huggingface \
+    HF_HUB_OFFLINE=0 \
+    SQLFORGE_BASE=Qwen/Qwen2.5-Coder-1.5B-Instruct \
+    SQLFORGE_ADAPTER=Abdullahkousa2/sqlforge-qwen2.5-coder-1.5b \
+    SQLFORGE_4BIT=0 \
+    SQLFORGE_DB_DIR=/app/demo_dbs
+
+EXPOSE 8000
+CMD ["uvicorn", "app.server:app", "--host", "0.0.0.0", "--port", "8000"]

app/server.py

@@ -0,0 +1,189 @@
+"""
+SQLForge — demo server.
+
+A FastAPI app that loads the fine-tuned text-to-SQL model and turns a natural
+-language question + database schema into a SQL query. When a real SQLite
+database is available it also *runs* the query, shows the results, and uses
+self-correction (feed the DB error back to the model and retry) so you can watch
+the agent fix its own mistakes.
+
+Run locally:
+    uvicorn app.server:app --reload --port 8000
+Then open http://localhost:8000
+"""
+import os
+import sqlite3
+import threading
+import time
+from pathlib import Path
+
+# the model + tokenizer are local; don't reach for the (flaky) HF CDN at serve time.
+os.environ.setdefault("HF_HUB_OFFLINE", "1")
+
+from fastapi import FastAPI, HTTPException
+from fastapi.responses import FileResponse
+from fastapi.staticfiles import StaticFiles
+from pydantic import BaseModel
+
+from sqlforge.exec_eval import run_sql, schema_from_sqlite
+from sqlforge.inference import generate_sql, generate_sql_with_retry, load_model
+
+ROOT = Path(__file__).resolve().parent.parent
+STATIC = Path(__file__).resolve().parent / "static"
+
+# --- config (all overridable by env, so HF Spaces / CI can swap paths) ----------
+BASE_MODEL = os.environ.get("SQLFORGE_BASE", "models/qwen2.5-coder-1.5b")
+if (ROOT / BASE_MODEL).is_dir():
+    BASE_MODEL = str(ROOT / BASE_MODEL)
+ADAPTER = os.environ.get("SQLFORGE_ADAPTER", str(ROOT / "outputs" / "qwen2.5-coder-1.5b-sql"))
+FOUR_BIT = os.environ.get("SQLFORGE_4BIT", "1") == "1"
+DB_DIR = Path(os.environ.get("SQLFORGE_DB_DIR",
+                             str(ROOT / "data" / "spider_raw" / "spider_data" / "database")))
+MAX_ROWS = 100    # cap result rows sent to the browser
+GEN_TOKENS = 192  # SQL is short; cap new tokens for a snappier demo
+MAX_RETRIES = 1   # one self-correction retry (worst case ~2 generations, not 3)
+
+# curated example databases — every question below is verified to run cleanly
+# against the real DB. The last car question deliberately triggers self-correction
+# (a JOIN it fixes itself) to showcase the agentic recovery succeeding.
+EXAMPLES = [
+    {"db_id": "concert_singer", "label": "Concerts & Singers",
+     "questions": ["How many singers do we have?",
+                   "What is the average, minimum, and maximum age of all singers?",
+                   "Show the name and country of all singers ordered by age from oldest to youngest."]},
+    {"db_id": "pets_1", "label": "Students & Pets",
+     "questions": ["How many pets are there?",
+                   "What is the average weight of all pets?",
+                   "How many students are there?"]},
+    {"db_id": "world_1", "label": "World (countries)",
+     "questions": ["What are the names of all countries that became independent after 1950?",
+                   "How many countries have a republic as their form of government?",
+                   "What is the average life expectancy of countries in Africa?"]},
+    {"db_id": "car_1", "label": "Cars",
+     "questions": ["How many continents are there?",
+                   "What is the maximum horsepower of any car?",
+                   "How many countries does each continent have? List continent id, name and count."]},
+    {"db_id": "student_transcripts_tracking", "label": "Student Transcripts",
+     "questions": ["How many courses in total are listed?",
+                   "How many students are there?",
+                   "List the first and last name of every student."]},
+]
+
+# --- model state (loaded in the background so the server starts instantly) ------
+STATE = {"status": "loading", "model": ADAPTER, "device": None, "error": None}
+_MODEL = {"model": None, "tok": None}
+_LOCK = threading.Lock()  # one generation at a time (single GPU)
+
+
+def _load():
+    try:
+        model, tok = load_model(BASE_MODEL, adapter_path=ADAPTER, four_bit=FOUR_BIT)
+        _MODEL["model"], _MODEL["tok"] = model, tok
+        STATE["device"] = str(getattr(model, "device", "cuda"))
+        STATE["status"] = "online"
+        print(f"[sqlforge] model online ({STATE['device']}, 4bit={FOUR_BIT})")
+    except Exception as exc:  # noqa: BLE001
+        STATE["status"] = "error"
+        STATE["error"] = str(exc)
+        print(f"[sqlforge] model failed to load: {exc}")
+
+
+app = FastAPI(title="SQLForge", description="Fine-tuned text-to-SQL demo")
+
+
+@app.on_event("startup")
+def _startup():
+    threading.Thread(target=_load, daemon=True).start()
+
+
+def _db_path(db_id: str) -> Path | None:
+    """Resolve a known example db_id to its .sqlite file (no path traversal)."""
+    if not db_id or "/" in db_id or "\\" in db_id or ".." in db_id:
+        return None
+    p = DB_DIR / db_id / f"{db_id}.sqlite"
+    return p if p.exists() else None
+
+
+# --- API ------------------------------------------------------------------------
+class GenerateRequest(BaseModel):
+    question: str
+    schema_text: str | None = None   # raw CREATE TABLE text (custom mode)
+    db_id: str | None = None         # example DB id (executes + self-corrects)
+    self_correct: bool = True
+
+
+@app.get("/api/health")
+def health():
+    return STATE
+
+
+@app.get("/api/examples")
+def examples():
+    return [e for e in EXAMPLES if _db_path(e["db_id"])]
+
+
+@app.get("/api/schema")
+def schema(db_id: str):
+    p = _db_path(db_id)
+    if not p:
+        raise HTTPException(404, f"unknown database '{db_id}'")
+    return {"db_id": db_id, "schema": schema_from_sqlite(p)}
+
+
+@app.post("/api/generate")
+def generate(req: GenerateRequest):
+    if STATE["status"] != "online":
+        raise HTTPException(503, f"model not ready ({STATE['status']})")
+    if not req.question.strip():
+        raise HTTPException(400, "question is required")
+
+    db_path = _db_path(req.db_id) if req.db_id else None
+    schema_text = req.schema_text
+    if db_path and not schema_text:
+        schema_text = schema_from_sqlite(db_path)
+    if not schema_text:
+        raise HTTPException(400, "provide a schema or pick an example database")
+
+    model, tok = _MODEL["model"], _MODEL["tok"]
+    trace: list = []
+    t0 = time.time()
+    with _LOCK:
+        if db_path and req.self_correct:
+            sql, attempts = generate_sql_with_retry(
+                model, tok, schema_text, req.question,
+                validate=lambda s: run_sql(db_path, s)[1],
+                max_retries=MAX_RETRIES, max_new_tokens=GEN_TOKENS, trace=trace)
+        else:
+            sql = generate_sql(model, tok, schema_text, req.question,
+                               max_new_tokens=GEN_TOKENS)
+            attempts = 1
+    elapsed = round(time.time() - t0, 2)
+
+    resp = {"sql": sql, "attempts": attempts, "trace": trace,
+            "self_corrected": attempts > 1, "elapsed_s": elapsed,
+            "executed": False, "columns": None, "rows": None,
+            "row_count": None, "error": None}
+
+    # if we have the real DB, run the final query and return the result preview
+    if db_path:
+        conn = sqlite3.connect(str(db_path))
+        try:
+            cur = conn.execute(sql)
+            cols = [c[0] for c in cur.description] if cur.description else []
+            rows = cur.fetchmany(MAX_ROWS)
+            resp.update(executed=True, columns=cols,
+                        rows=[list(r) for r in rows], row_count=len(rows))
+        except Exception as exc:  # noqa: BLE001
+            resp.update(executed=True, error=str(exc))
+        finally:
+            conn.close()
+    return resp
+
+
+# --- static frontend (mounted last so /api/* wins) ------------------------------
+@app.get("/")
+def index():
+    return FileResponse(STATIC / "index.html")
+
+
+app.mount("/", StaticFiles(directory=str(STATIC)), name="static")

app/static/app.js

@@ -0,0 +1,141 @@
+// SQLForge demo — frontend logic
+const $ = (id) => document.getElementById(id);
+const dbSelect = $("dbSelect"), questionEl = $("question"), examplesEl = $("examples"),
+      schemaView = $("schemaView"), runBtn = $("runBtn"),
+      placeholder = $("placeholder"), result = $("result"),
+      sqlOut = $("sqlOut"), badges = $("badges"),
+      traceBlock = $("traceBlock"), traceList = $("traceList"),
+      resultsBlock = $("resultsBlock"), resultsHead = $("resultsHead"),
+      resultsTable = $("resultsTable"), errorBlock = $("errorBlock"), errorOut = $("errorOut");
+
+let EXAMPLES = [], modelReady = false;
+
+// ---------- model status ----------
+async function pollHealth() {
+  const el = $("status"), label = $("statusLabel");
+  try {
+    const h = await (await fetch("/api/health")).json();
+    if (h.status === "online") { el.dataset.state = "online"; label.textContent = "model online"; modelReady = true; }
+    else if (h.status === "loading") { el.dataset.state = "loading"; label.textContent = "loading model…"; modelReady = false; }
+    else { el.dataset.state = "error"; label.textContent = "model error"; modelReady = false; }
+  } catch { el.dataset.state = "offline"; label.textContent = "offline"; modelReady = false; }
+  updateRunBtn();
+}
+function updateRunBtn() {
+  runBtn.disabled = !modelReady || runBtn.classList.contains("loading");
+}
+
+// ---------- examples + schema ----------
+async function loadExamples() {
+  EXAMPLES = await (await fetch("/api/examples")).json();
+  dbSelect.innerHTML = EXAMPLES.map(e => `<option value="${e.db_id}">${e.label}</option>`).join("");
+  if (EXAMPLES.length) { await onDbChange(); }
+}
+async function onDbChange() {
+  const ex = EXAMPLES.find(e => e.db_id === dbSelect.value);
+  examplesEl.innerHTML = (ex?.questions || [])
+    .map(q => `<span class="chip" title="${esc(q)}">${esc(q)}</span>`).join("");
+  examplesEl.querySelectorAll(".chip").forEach((c, i) => {
+    c.onclick = () => { questionEl.value = ex.questions[i]; questionEl.focus(); };
+  });
+  try {
+    const s = await (await fetch(`/api/schema?db_id=${encodeURIComponent(dbSelect.value)}`)).json();
+    schemaView.textContent = s.schema;
+  } catch { schemaView.textContent = "—"; }
+}
+
+// ---------- generate ----------
+async function run() {
+  const question = questionEl.value.trim();
+  if (!question || !modelReady) return;
+  runBtn.classList.add("loading"); updateRunBtn();
+  runBtn.querySelector(".btn-label").textContent = "Generating…";
+  try {
+    const resp = await fetch("/api/generate", {
+      method: "POST", headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ question, db_id: dbSelect.value, self_correct: true }),
+    });
+    if (!resp.ok) { const e = await resp.json().catch(() => ({})); throw new Error(e.detail || resp.statusText); }
+    render(await resp.json());
+  } catch (err) {
+    placeholder.classList.add("hidden"); result.classList.remove("hidden");
+    showError("Request failed", err.message);
+  } finally {
+    runBtn.classList.remove("loading"); updateRunBtn();
+    runBtn.querySelector(".btn-label").textContent = "Generate SQL";
+  }
+}
+
+function render(r) {
+  placeholder.classList.add("hidden"); result.classList.remove("hidden");
+  sqlOut.innerHTML = highlight(r.sql);
+
+  // badges
+  const b = [];
+  b.push(`<span class="badge">${r.elapsed_s}s</span>`);
+  if (r.self_corrected) b.push(`<span class="badge fix">🛠️ self-corrected (${r.attempts} tries)</span>`);
+  if (r.executed && !r.error) b.push(`<span class="badge good">✓ ran · ${r.row_count} row${r.row_count === 1 ? "" : "s"}</span>`);
+  if (r.executed && r.error) b.push(`<span class="badge warn">✕ execution error</span>`);
+  badges.innerHTML = b.join("");
+
+  // self-correction trace (only show if there was more than one attempt)
+  if (r.trace && r.trace.length > 1) {
+    traceList.innerHTML = r.trace.map(step => {
+      const ok = !step.error;
+      return `<div class="trace-step">
+        <div class="tlabel">Attempt ${step.attempt}
+          <span class="tag ${ok ? "ok" : "fail"}">${ok ? "ran clean" : "crashed"}</span></div>
+        <pre class="code sql mono">${highlight(step.sql)}</pre>
+        ${step.error ? `<div class="terr">↳ ${esc(step.error)}</div>` : ""}
+      </div>`;
+    }).join("");
+    traceBlock.classList.remove("hidden");
+  } else { traceBlock.classList.add("hidden"); }
+
+  // results / error
+  errorBlock.classList.add("hidden"); resultsBlock.classList.add("hidden");
+  if (r.executed && r.error) { showError("Execution error", r.error); }
+  else if (r.executed) { renderTable(r.columns, r.rows, r.row_count); }
+}
+
+function renderTable(cols, rows, n) {
+  if (!cols || !cols.length) { resultsBlock.classList.add("hidden"); return; }
+  resultsHead.textContent = `Query results — ${n} row${n === 1 ? "" : "s"}`;
+  const head = `<thead><tr>${cols.map(c => `<th>${esc(c)}</th>`).join("")}</tr></thead>`;
+  const body = `<tbody>${rows.map(row =>
+    `<tr>${row.map(c => `<td>${esc(c === null ? "NULL" : String(c))}</td>`).join("")}</tr>`).join("")}</tbody>`;
+  resultsTable.innerHTML = head + (rows.length ? body : `<tbody><tr><td colspan="${cols.length}" class="muted">(no rows returned)</td></tr></tbody>`);
+  resultsBlock.classList.remove("hidden");
+}
+
+function showError(title, msg) {
+  document.querySelector("#errorBlock .block-head span").textContent = title;
+  errorOut.textContent = msg; errorBlock.classList.remove("hidden");
+}
+
+// ---------- tiny SQL highlighter ----------
+const KW = /\b(SELECT|FROM|WHERE|JOIN|LEFT|RIGHT|INNER|OUTER|ON|AS|AND|OR|NOT|IN|IS|NULL|GROUP|BY|ORDER|HAVING|LIMIT|OFFSET|DISTINCT|UNION|ALL|INTERSECT|EXCEPT|INSERT|INTO|VALUES|UPDATE|SET|DELETE|CREATE|TABLE|LIKE|BETWEEN|ASC|DESC|CASE|WHEN|THEN|ELSE|END|EXISTS)\b/gi;
+const FN = /\b(COUNT|SUM|AVG|MIN|MAX|ROUND|ABS|LENGTH|LOWER|UPPER|SUBSTR|COALESCE|CAST)\b/gi;
+function highlight(sql) {
+  let h = esc(sql || "");
+  h = h.replace(/'([^']*)'/g, '<span class="str">\'$1\'</span>');
+  h = h.replace(/\b(\d+(\.\d+)?)\b/g, '<span class="num">$1</span>');
+  h = h.replace(FN, (m) => `<span class="fn">${m}</span>`);
+  h = h.replace(KW, (m) => `<span class="kw">${m}</span>`);
+  return h;
+}
+function esc(s) { return String(s).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;"); }
+
+// ---------- wire up ----------
+dbSelect.onchange = onDbChange;
+runBtn.onclick = run;
+questionEl.addEventListener("keydown", (e) => { if (e.key === "Enter" && (e.metaKey || e.ctrlKey)) run(); });
+$("copyBtn").onclick = () => {
+  navigator.clipboard.writeText(sqlOut.textContent).then(() => {
+    const b = $("copyBtn"); b.textContent = "copied!"; setTimeout(() => b.textContent = "copy", 1200);
+  });
+};
+
+loadExamples();
+pollHealth();
+setInterval(pollHealth, 4000);

app/static/index.html

@@ -0,0 +1,108 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>SQLForge — Text-to-SQL</title>
+  <link rel="stylesheet" href="/style.css" />
+</head>
+<body>
+  <div class="aurora" aria-hidden="true"></div>
+
+  <header class="topbar">
+    <div class="brand">
+      <div class="logo" aria-hidden="true">
+        <svg viewBox="0 0 24 24" width="22" height="22" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+          <ellipse cx="12" cy="5" rx="8" ry="3"/><path d="M4 5v6c0 1.7 3.6 3 8 3s8-1.3 8-3V5"/><path d="M4 11v6c0 1.7 3.6 3 8 3s8-1.3 8-3v-6"/>
+        </svg>
+      </div>
+      <div class="brand-text">
+        <span class="brand-name">SQL<span class="accent">Forge</span></span>
+        <span class="brand-sub">fine-tuned text-to-SQL</span>
+      </div>
+    </div>
+
+    <div class="status" id="status" data-state="loading" title="Model status">
+      <span class="dot"></span>
+      <span class="status-label" id="statusLabel">connecting…</span>
+    </div>
+  </header>
+
+  <main class="layout">
+    <!-- INPUT -->
+    <section class="panel input-panel">
+      <div class="panel-head">
+        <h2>Ask in plain English</h2>
+        <p class="muted">Pick a database, type a question, and watch the model write &amp; run the SQL.</p>
+      </div>
+
+      <label class="field-label" for="dbSelect">Database</label>
+      <div class="select-wrap">
+        <select id="dbSelect"></select>
+      </div>
+
+      <label class="field-label" for="question">Question</label>
+      <textarea id="question" rows="3" placeholder="e.g. How many singers do we have?"></textarea>
+
+      <div class="examples" id="examples"></div>
+
+      <details class="schema-box">
+        <summary>Schema being used <span class="chev">›</span></summary>
+        <pre id="schemaView" class="code mono">—</pre>
+      </details>
+
+      <button id="runBtn" class="run-btn">
+        <span class="btn-label">Generate SQL</span>
+        <span class="spinner" aria-hidden="true"></span>
+      </button>
+    </section>
+
+    <!-- OUTPUT -->
+    <section class="panel output-panel">
+      <div class="panel-head row">
+        <h2>Result</h2>
+        <div class="badges" id="badges"></div>
+      </div>
+
+      <div id="placeholder" class="placeholder">
+        <svg viewBox="0 0 24 24" width="40" height="40" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round">
+          <path d="m18 16 4-4-4-4"/><path d="m6 8-4 4 4 4"/><path d="m14.5 4-5 16"/>
+        </svg>
+        <p>Your generated query and live results will appear here.</p>
+      </div>
+
+      <div id="result" class="result hidden">
+        <div class="block">
+          <div class="block-head"><span>Generated SQL</span><button class="copy" id="copyBtn">copy</button></div>
+          <pre id="sqlOut" class="code sql mono"></pre>
+        </div>
+
+        <div id="traceBlock" class="block trace hidden">
+          <div class="block-head"><span>🛠️ Self-correction trace</span></div>
+          <div id="traceList"></div>
+        </div>
+
+        <div id="resultsBlock" class="block hidden">
+          <div class="block-head"><span id="resultsHead">Query results</span></div>
+          <div class="table-scroll"><table id="resultsTable"></table></div>
+        </div>
+
+        <div id="errorBlock" class="block error hidden">
+          <div class="block-head"><span>Execution error</span></div>
+          <pre id="errorOut" class="code mono"></pre>
+        </div>
+      </div>
+    </section>
+  </main>
+
+  <footer class="footer">
+    <span>Qwen2.5-Coder-1.5B · QLoRA · Spider</span>
+    <span class="sep">•</span>
+    <span><b class="accent">65.6%</b> execution accuracy <span class="muted">(vs 57.4% base)</span></span>
+    <span class="sep">•</span>
+    <span class="muted">runs SQL against real SQLite DBs</span>
+  </footer>
+
+  <script src="/app.js"></script>
+</body>
+</html>

app/static/style.css

@@ -0,0 +1,253 @@
+/* SQLForge — dark "forge" theme: deep slate + molten amber, cyan for SQL */
+:root {
+  --bg: #0a0e16;
+  --bg-2: #0e131e;
+  --panel: #131a28;
+  --panel-2: #161e2e;
+  --border: #243149;
+  --border-soft: #1c2638;
+  --text: #e7ecf4;
+  --text-dim: #9aa7bd;
+  --muted: #6b7890;
+  --amber: #f59e0b;
+  --amber-2: #f97316;
+  --cyan: #38bdf8;
+  --green: #34d399;
+  --red: #f87171;
+  --radius: 14px;
+  --shadow: 0 18px 50px -18px rgba(0,0,0,.7);
+  --mono: "JetBrains Mono", ui-monospace, "SF Mono", Menlo, Consolas, monospace;
+  --sans: "Inter", system-ui, -apple-system, Segoe UI, Roboto, sans-serif;
+}
+
+* { box-sizing: border-box; }
+html, body { margin: 0; padding: 0; }
+body {
+  font-family: var(--sans);
+  background: var(--bg);
+  color: var(--text);
+  min-height: 100vh;
+  line-height: 1.55;
+  -webkit-font-smoothing: antialiased;
+  position: relative;
+  overflow-x: hidden;
+}
+
+/* ambient glow */
+.aurora {
+  position: fixed; inset: 0; z-index: 0; pointer-events: none;
+  background:
+    radial-gradient(60rem 40rem at 78% -8%, rgba(249,115,22,.16), transparent 60%),
+    radial-gradient(48rem 34rem at 8% 4%, rgba(56,189,248,.10), transparent 55%),
+    radial-gradient(40rem 40rem at 50% 120%, rgba(245,158,11,.08), transparent 60%);
+}
+
+/* ---------- top bar ---------- */
+.topbar {
+  position: relative; z-index: 2;
+  display: flex; align-items: center; justify-content: space-between;
+  padding: 18px clamp(18px, 4vw, 44px);
+  border-bottom: 1px solid var(--border-soft);
+  background: rgba(10,14,22,.6);
+  backdrop-filter: blur(10px);
+}
+.brand { display: flex; align-items: center; gap: 13px; }
+.logo {
+  display: grid; place-items: center;
+  width: 42px; height: 42px; border-radius: 12px;
+  color: #1a1205;
+  background: linear-gradient(140deg, var(--amber), var(--amber-2));
+  box-shadow: 0 6px 20px -6px rgba(245,158,11,.6);
+}
+.brand-text { display: flex; flex-direction: column; line-height: 1.1; }
+.brand-name { font-weight: 800; font-size: 19px; letter-spacing: -.02em; }
+.brand-sub { font-size: 12px; color: var(--muted); letter-spacing: .02em; }
+.accent {
+  background: linear-gradient(120deg, var(--amber), var(--amber-2));
+  -webkit-background-clip: text; background-clip: text; color: transparent;
+}
+
+/* status pill */
+.status {
+  display: inline-flex; align-items: center; gap: 9px;
+  padding: 8px 14px; border-radius: 999px;
+  font-size: 13px; font-weight: 600;
+  border: 1px solid var(--border);
+  background: var(--panel);
+}
+.status .dot {
+  width: 9px; height: 9px; border-radius: 50%; background: var(--muted);
+  box-shadow: 0 0 0 0 rgba(0,0,0,0);
+}
+.status[data-state="online"] { color: var(--green); border-color: rgba(52,211,153,.35); }
+.status[data-state="online"] .dot { background: var(--green); box-shadow: 0 0 10px 1px rgba(52,211,153,.7); }
+.status[data-state="loading"] { color: var(--amber); border-color: rgba(245,158,11,.35); }
+.status[data-state="loading"] .dot { background: var(--amber); animation: pulse 1.2s infinite; }
+.status[data-state="error"],
+.status[data-state="offline"] { color: var(--red); border-color: rgba(248,113,113,.35); }
+.status[data-state="error"] .dot,
+.status[data-state="offline"] .dot { background: var(--red); }
+@keyframes pulse { 0%,100%{opacity:1} 50%{opacity:.35} }
+
+/* ---------- layout ---------- */
+.layout {
+  position: relative; z-index: 1;
+  display: grid; grid-template-columns: minmax(0,1fr) minmax(0,1.15fr);
+  gap: 22px;
+  padding: clamp(18px, 3vw, 32px) clamp(18px, 4vw, 44px);
+  max-width: 1280px; margin: 0 auto;
+}
+@media (max-width: 880px) { .layout { grid-template-columns: 1fr; } }
+
+.panel {
+  background: linear-gradient(180deg, var(--panel), var(--bg-2));
+  border: 1px solid var(--border-soft);
+  border-radius: var(--radius);
+  padding: 22px;
+  box-shadow: var(--shadow);
+}
+.panel-head h2 { margin: 0 0 4px; font-size: 16px; font-weight: 700; letter-spacing: -.01em; }
+.panel-head.row { display: flex; align-items: center; justify-content: space-between; gap: 12px; }
+.muted { color: var(--muted); }
+.panel-head p { margin: 0 0 6px; font-size: 13px; }
+
+/* ---------- form ---------- */
+.field-label {
+  display: block; margin: 16px 0 7px;
+  font-size: 12px; font-weight: 600; text-transform: uppercase;
+  letter-spacing: .06em; color: var(--text-dim);
+}
+.select-wrap { position: relative; }
+.select-wrap::after {
+  content: "▾"; position: absolute; right: 14px; top: 50%; transform: translateY(-50%);
+  color: var(--muted); pointer-events: none; font-size: 12px;
+}
+select, textarea {
+  width: 100%; font-family: var(--sans); font-size: 14px; color: var(--text);
+  background: var(--bg); border: 1px solid var(--border);
+  border-radius: 10px; padding: 12px 14px; outline: none;
+  transition: border-color .15s, box-shadow .15s;
+}
+select { appearance: none; cursor: pointer; padding-right: 34px; }
+textarea { resize: vertical; min-height: 64px; }
+select:focus, textarea:focus {
+  border-color: var(--amber);
+  box-shadow: 0 0 0 3px rgba(245,158,11,.15);
+}
+
+.examples { display: flex; flex-wrap: wrap; gap: 8px; margin-top: 12px; }
+.chip {
+  font-size: 12.5px; color: var(--text-dim); cursor: pointer;
+  background: var(--panel-2); border: 1px solid var(--border);
+  padding: 7px 12px; border-radius: 999px;
+  transition: all .15s; line-height: 1.3; max-width: 100%;
+  white-space: nowrap; overflow: hidden; text-overflow: ellipsis;
+}
+.chip:hover { color: var(--text); border-color: var(--amber); background: rgba(245,158,11,.08); }
+
+.schema-box { margin-top: 16px; border-top: 1px solid var(--border-soft); padding-top: 12px; }
+.schema-box summary {
+  cursor: pointer; font-size: 13px; color: var(--text-dim); font-weight: 600;
+  list-style: none; display: flex; align-items: center; gap: 6px;
+}
+.schema-box summary::-webkit-details-marker { display: none; }
+.schema-box .chev { transition: transform .2s; color: var(--muted); }
+.schema-box[open] .chev { transform: rotate(90deg); }
+.schema-box pre { margin: 10px 0 0; max-height: 220px; overflow: auto; }
+
+/* run button */
+.run-btn {
+  position: relative; width: 100%; margin-top: 18px;
+  font-family: var(--sans); font-size: 15px; font-weight: 700; color: #1a1205;
+  background: linear-gradient(120deg, var(--amber), var(--amber-2));
+  border: none; border-radius: 11px; padding: 13px 18px; cursor: pointer;
+  display: flex; align-items: center; justify-content: center; gap: 10px;
+  box-shadow: 0 10px 26px -10px rgba(245,158,11,.65);
+  transition: transform .12s, box-shadow .12s, filter .12s;
+}
+.run-btn:hover { transform: translateY(-1px); filter: brightness(1.05); }
+.run-btn:active { transform: translateY(0); }
+.run-btn:disabled { cursor: not-allowed; filter: grayscale(.4) brightness(.8); box-shadow: none; }
+.run-btn .spinner {
+  width: 16px; height: 16px; border-radius: 50%; display: none;
+  border: 2px solid rgba(26,18,5,.35); border-top-color: #1a1205;
+  animation: spin .7s linear infinite;
+}
+.run-btn.loading .spinner { display: inline-block; }
+@keyframes spin { to { transform: rotate(360deg); } }
+
+/* ---------- output ---------- */
+.badges { display: flex; flex-wrap: wrap; gap: 7px; }
+.badge {
+  font-size: 11.5px; font-weight: 600; padding: 4px 10px; border-radius: 999px;
+  border: 1px solid var(--border); color: var(--text-dim); background: var(--panel-2);
+  white-space: nowrap;
+}
+.badge.good { color: var(--green); border-color: rgba(52,211,153,.35); background: rgba(52,211,153,.08); }
+.badge.fix  { color: var(--amber); border-color: rgba(245,158,11,.35); background: rgba(245,158,11,.08); }
+.badge.warn { color: var(--red); border-color: rgba(248,113,113,.35); background: rgba(248,113,113,.08); }
+
+.placeholder {
+  display: flex; flex-direction: column; align-items: center; justify-content: center;
+  gap: 14px; text-align: center; color: var(--muted);
+  min-height: 320px; border: 1px dashed var(--border); border-radius: 12px; margin-top: 16px;
+}
+.placeholder svg { color: var(--border); }
+
+.result { margin-top: 16px; display: flex; flex-direction: column; gap: 14px; }
+.hidden { display: none !important; }
+
+.block { border: 1px solid var(--border-soft); border-radius: 11px; overflow: hidden; background: var(--bg); }
+.block-head {
+  display: flex; align-items: center; justify-content: space-between;
+  padding: 9px 14px; font-size: 12.5px; font-weight: 600; color: var(--text-dim);
+  background: var(--panel-2); border-bottom: 1px solid var(--border-soft);
+}
+.block.trace .block-head { color: var(--amber); }
+.block.error { border-color: rgba(248,113,113,.4); }
+.block.error .block-head { color: var(--red); background: rgba(248,113,113,.07); }
+
+.code { font-family: var(--mono); font-size: 13px; padding: 14px; margin: 0; overflow: auto; line-height: 1.6; }
+pre.code { white-space: pre-wrap; word-break: break-word; }
+.sql .kw { color: var(--cyan); font-weight: 600; }
+.sql .fn { color: var(--amber); }
+.sql .str { color: var(--green); }
+.sql .num { color: #c4b5fd; }
+
+.copy {
+  font-family: var(--sans); font-size: 11.5px; color: var(--text-dim); cursor: pointer;
+  background: transparent; border: 1px solid var(--border); border-radius: 6px; padding: 3px 9px;
+  transition: all .15s;
+}
+.copy:hover { color: var(--text); border-color: var(--amber); }
+
+/* self-correction trace */
+.trace-step { padding: 11px 14px; border-bottom: 1px solid var(--border-soft); }
+.trace-step:last-child { border-bottom: none; }
+.trace-step .tlabel { font-size: 12px; font-weight: 600; margin-bottom: 6px; display: flex; align-items: center; gap: 7px; }
+.trace-step .tlabel .tag { font-size: 10.5px; padding: 2px 7px; border-radius: 999px; }
+.trace-step .tag.fail { color: var(--red); background: rgba(248,113,113,.12); }
+.trace-step .tag.ok { color: var(--green); background: rgba(52,211,153,.12); }
+.trace-step pre { margin: 0; font-size: 12.5px; }
+.trace-step .terr { color: var(--red); font-size: 12px; margin-top: 6px; font-family: var(--mono); }
+
+/* results table */
+.table-scroll { overflow: auto; max-height: 360px; }
+table { width: 100%; border-collapse: collapse; font-size: 13px; }
+th, td {
+  text-align: left; padding: 8px 14px; border-bottom: 1px solid var(--border-soft);
+  white-space: nowrap; font-family: var(--mono); font-size: 12.5px;
+}
+th { position: sticky; top: 0; background: var(--panel-2); color: var(--text-dim); font-weight: 600; z-index: 1; }
+td { color: var(--text); }
+tbody tr:hover td { background: rgba(255,255,255,.02); }
+
+/* footer */
+.footer {
+  position: relative; z-index: 1;
+  display: flex; flex-wrap: wrap; align-items: center; justify-content: center; gap: 10px;
+  padding: 22px 18px 32px; font-size: 12.5px; color: var(--text-dim);
+  border-top: 1px solid var(--border-soft); margin-top: 8px;
+}
+.footer .sep { color: var(--border); }
+.footer b { font-weight: 700; }

demo_dbs/world_1/world_1.sqlite

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:17b986695f16786d58d66f85e49dba87bdfe72953207ab9b1b49da9d2301ef65
+size 319488

requirements-serve.txt

@@ -0,0 +1,8 @@
+# Lean serving deps for the HF Space (CPU). torch is installed separately in the
+# Dockerfile (CPU wheel). No bitsandbytes/trl/datasets/wandb — those are train-only.
+transformers>=4.45.0
+peft>=0.13.0
+accelerate>=1.0.0
+fastapi>=0.111.0
+uvicorn[standard]>=0.30.0
+huggingface_hub>=0.25.0

sqlforge/__init__.py

@@ -0,0 +1,3 @@
+"""SQLForge — fine-tuned text-to-SQL: shared library for prompts, inference, and eval."""
+
+__version__ = "0.1.0"

sqlforge/cli.py

@@ -0,0 +1,58 @@
+"""sqlforge CLI — generate (and optionally run) SQL from a natural-language question.
+
+Examples:
+    sqlforge -q "How many users signed up after 2020?" --db app.sqlite --run
+    sqlforge -q "list all singers" --schema 'CREATE TABLE singer ("Name" text);'
+"""
+import argparse
+import os
+import sys
+
+DEFAULT_BASE = "Qwen/Qwen2.5-Coder-1.5B-Instruct"
+DEFAULT_ADAPTER = "Abdullahkousa2/sqlforge-qwen2.5-coder-1.5b"
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser(
+        prog="sqlforge",
+        description="Turn a natural-language question into SQL with the fine-tuned SQLForge model.")
+    ap.add_argument("-q", "--question", required=True, help="the question to answer in SQL")
+    src = ap.add_mutually_exclusive_group(required=True)
+    src.add_argument("--db", help="path to a SQLite database (schema auto-extracted)")
+    src.add_argument("--schema", help="raw CREATE TABLE text, or a path to a .sql file")
+    ap.add_argument("--base", default=DEFAULT_BASE, help="base model (HF id or local path)")
+    ap.add_argument("--adapter", default=DEFAULT_ADAPTER,
+                    help="LoRA adapter (HF id or local path); pass 'none' for the plain base model")
+    ap.add_argument("--no-4bit", action="store_true",
+                    help="load in bf16/fp32 instead of 4-bit (use this on CPU)")
+    ap.add_argument("--run", action="store_true", help="also execute the query (requires --db)")
+    args = ap.parse_args()
+
+    from .inference import generate_sql, generate_sql_with_retry, load_model
+
+    if args.db:
+        from .exec_eval import schema_from_sqlite
+        schema = schema_from_sqlite(args.db)
+    else:
+        schema = open(args.schema, encoding="utf-8").read() if os.path.isfile(args.schema) else args.schema
+
+    adapter = None if (args.adapter or "").lower() == "none" else args.adapter
+    model, tok = load_model(args.base, adapter_path=adapter, four_bit=not args.no_4bit)
+
+    if args.db and args.run:
+        from .exec_eval import run_sql
+        sql, _ = generate_sql_with_retry(
+            model, tok, schema, args.question, validate=lambda s: run_sql(args.db, s)[1])
+        print(sql)
+        rows, err = run_sql(args.db, sql)
+        if err:
+            print(f"-- execution error: {err}", file=sys.stderr)
+            sys.exit(1)
+        for row in rows[:50]:
+            print(row)
+    else:
+        print(generate_sql(model, tok, schema, args.question))
+
+
+if __name__ == "__main__":
+    main()

sqlforge/exec_eval.py

@@ -0,0 +1,76 @@
+"""
+Execution accuracy — the real metric.
+
+A predicted query is correct if, run against the actual SQLite database, it
+returns the SAME result set as the gold query. This is far more meaningful than
+string matching: two very different-looking queries can be equally correct, and
+two near-identical strings can differ by one wrong column.
+
+Comparison is order-insensitive (a multiset of rows) unless the gold query
+contains ORDER BY, in which case row order must match too.
+"""
+import sqlite3
+import threading
+from pathlib import Path
+
+
+def db_file(db_root: str | Path, db_id: str) -> Path:
+    """Path to a Spider database: <db_root>/<db_id>/<db_id>.sqlite"""
+    return Path(db_root) / db_id / f"{db_id}.sqlite"
+
+
+def schema_from_sqlite(path: str | Path) -> str:
+    """Reconstruct the CREATE TABLE schema string from a SQLite file.
+
+    Matches the format the model was trained on (the raw DDL from sqlite_master),
+    so the demo server can feed the model a real DB's schema with no extra work.
+    """
+    conn = sqlite3.connect(str(path))
+    try:
+        rows = conn.execute(
+            "SELECT sql FROM sqlite_master "
+            "WHERE type='table' AND sql IS NOT NULL "
+            "AND name NOT LIKE 'sqlite_%' ORDER BY name"
+        ).fetchall()
+    finally:
+        conn.close()
+    return "\n\n".join(r[0].strip() + ";" for r in rows)
+
+
+def run_sql(path: str | Path, sql: str, timeout: float = 15.0):
+    """Execute SQL; return (rows, error). A watchdog interrupts runaway queries."""
+    conn = sqlite3.connect(str(path))
+    conn.text_factory = lambda b: b.decode("utf-8", errors="ignore") if isinstance(b, bytes) else b
+    watchdog = threading.Timer(timeout, conn.interrupt)
+    watchdog.start()
+    try:
+        cur = conn.execute(sql)
+        return cur.fetchall(), None
+    except Exception as exc:  # noqa: BLE001 - any SQL/exec error => prediction is wrong
+        return None, str(exc)
+    finally:
+        watchdog.cancel()
+        conn.close()
+
+
+def _norm(rows, order_sensitive: bool):
+    """Stringify cells so types compare cleanly; sort unless order matters."""
+    table = [tuple(str(c) for c in row) for row in rows]
+    return table if order_sensitive else sorted(table)
+
+
+def execution_match(path: str | Path, pred_sql: str, gold_sql: str):
+    """
+    Return (is_correct, error).
+      is_correct = True/False, or None if the GOLD query itself fails (skip example).
+    """
+    gold_rows, gerr = run_sql(path, gold_sql)
+    if gerr is not None:
+        return None, f"gold failed: {gerr}"
+
+    pred_rows, perr = run_sql(path, pred_sql)
+    if perr is not None:
+        return False, perr
+
+    order_sensitive = "order by" in gold_sql.lower()
+    return _norm(pred_rows, order_sensitive) == _norm(gold_rows, order_sensitive), None

sqlforge/inference.py

@@ -0,0 +1,100 @@
+"""
+Model loading + SQL generation. Shared by the eval harness and the demo server.
+"""
+import re
+
+import torch
+from transformers import AutoModelForCausalLM, AutoTokenizer, BitsAndBytesConfig
+
+from .prompts import build_correction_messages, build_inference_messages
+
+DEFAULT_BASE = "Qwen/Qwen2.5-Coder-1.5B-Instruct"
+
+_SQL_FENCE = re.compile(r"```(?:sql)?\s*(.*?)\s*```", re.DOTALL | re.IGNORECASE)
+
+
+def load_model(base_model: str = DEFAULT_BASE, adapter_path: str | None = None,
+               four_bit: bool = True):
+    """Load the base model (4-bit by default) and optionally attach a LoRA adapter."""
+    tok = AutoTokenizer.from_pretrained(base_model)
+    kwargs = {"torch_dtype": torch.bfloat16, "device_map": "auto"}
+    if four_bit:
+        kwargs["quantization_config"] = BitsAndBytesConfig(
+            load_in_4bit=True,
+            bnb_4bit_quant_type="nf4",
+            bnb_4bit_compute_dtype=torch.bfloat16,
+            bnb_4bit_use_double_quant=True,
+        )
+    model = AutoModelForCausalLM.from_pretrained(base_model, **kwargs)
+    if adapter_path:
+        from peft import PeftModel
+        model = PeftModel.from_pretrained(model, adapter_path)
+    model.eval()
+    return model, tok
+
+
+def clean_sql(text: str) -> str:
+    """Strip markdown fences / prose; keep a single SQL statement."""
+    text = text.strip()
+    m = _SQL_FENCE.search(text)
+    if m:
+        text = m.group(1).strip()
+    # cut at first statement terminator, drop trailing chatter
+    if ";" in text:
+        text = text.split(";")[0]
+    return " ".join(text.split()).strip()
+
+
+@torch.no_grad()
+def _generate_from_messages(model, tok, msgs: list[dict], max_new_tokens: int = 256) -> str:
+    prompt = tok.apply_chat_template(msgs, tokenize=False, add_generation_prompt=True)
+    inputs = tok(prompt, return_tensors="pt").to(model.device)
+    out = model.generate(
+        **inputs,
+        max_new_tokens=max_new_tokens,
+        do_sample=False,            # greedy — deterministic, reproducible eval
+        pad_token_id=tok.eos_token_id,
+    )
+    gen = out[0][inputs["input_ids"].shape[1]:]
+    return clean_sql(tok.decode(gen, skip_special_tokens=True))
+
+
+def generate_sql(model, tok, schema: str, question: str, max_new_tokens: int = 256) -> str:
+    return _generate_from_messages(
+        model, tok, build_inference_messages(schema, question), max_new_tokens)
+
+
+def generate_sql_with_retry(model, tok, schema: str, question: str, validate,
+                            max_retries: int = 2, max_new_tokens: int = 256,
+                            trace: list | None = None):
+    """Generate SQL, then self-correct if it crashes against the database.
+
+    `validate(sql) -> error_str_or_None` runs the query and returns the DB error
+    (or None if it executes). On error we feed the failed query + error back to
+    the model and regenerate, up to `max_retries` times. Returns
+    (final_sql, attempts) where attempts == 1 means no correction was needed.
+
+    If `trace` is provided, each attempt is appended as
+    {"attempt": n, "sql": ..., "error": ...} — used by the demo UI to show the
+    agent fixing itself.
+
+    Note: this only fixes queries that *crash*. A query that runs but returns the
+    wrong rows is left alone — there's no error signal to correct against.
+    """
+    sql = generate_sql(model, tok, schema, question, max_new_tokens)
+    err = validate(sql)
+    attempts = 1
+    if trace is not None:
+        trace.append({"attempt": attempts, "sql": sql, "error": err})
+    while err is not None and attempts <= max_retries:
+        msgs = build_correction_messages(schema, question, sql, err)
+        fixed = _generate_from_messages(model, tok, msgs, max_new_tokens)
+        attempts += 1
+        new_err = validate(fixed)
+        # accept the retry if it now runs, or as the new working draft to refine
+        sql, err = fixed, new_err
+        if trace is not None:
+            trace.append({"attempt": attempts, "sql": sql, "error": err})
+        if err is None:
+            break
+    return sql, attempts

sqlforge/prompts.py

@@ -0,0 +1,105 @@
+"""
+Single source of truth for the prompt format.
+
+Both data prep (training) and inference (eval + serving) import from here, so the
+model is always evaluated with the exact format it was trained on — no skew.
+"""
+import re
+
+SYSTEM_PROMPT = (
+    "You are an expert data analyst. Given a SQLite database schema and a "
+    "question, write a single valid SQLite SQL query that answers it. "
+    "Respond with only the SQL query and nothing else."
+)
+
+
+def build_user(schema: str, question: str) -> str:
+    return f"Database schema:\n{schema}\n\nQuestion: {question}"
+
+
+def build_messages(schema: str, question: str, query: str) -> list[dict]:
+    """Full training example (system + user + assistant)."""
+    return [
+        {"role": "system", "content": SYSTEM_PROMPT},
+        {"role": "user", "content": build_user(schema, question)},
+        {"role": "assistant", "content": query},
+    ]
+
+
+def build_inference_messages(schema: str, question: str) -> list[dict]:
+    """Prompt for generation (no assistant turn — model completes it)."""
+    return [
+        {"role": "system", "content": SYSTEM_PROMPT},
+        {"role": "user", "content": build_user(schema, question)},
+    ]
+
+
+_CREATE_RE = re.compile(r'CREATE\s+TABLE\s+["`\[]?(\w+)', re.IGNORECASE)
+_COL_RE = re.compile(r'^["`\[]?(\w+)["`\]]?\s+\w')
+_SKIP = {"PRIMARY", "FOREIGN", "UNIQUE", "CONSTRAINT", "CHECK", "KEY"}
+
+
+def schema_identifiers(schema: str) -> dict[str, list[str]]:
+    """Parse a CREATE TABLE schema string into {table: [columns]}.
+
+    The model's crashes are almost always invented/pluralised identifiers, so we
+    hand it the *exact* names back in the correction prompt. Line-based parse
+    matches the one-column-per-line DDL both the dataset and SQLite produce.
+    """
+    tables: dict[str, list[str]] = {}
+    current = None
+    for raw in schema.splitlines():
+        line = raw.strip()
+        m = _CREATE_RE.match(line)
+        if m:
+            current = m.group(1)
+            tables[current] = []
+            continue
+        if current is None:
+            continue
+        if line.startswith(")"):
+            current = None
+            continue
+        toks = line.split()
+        if toks and toks[0].strip('("`[]').upper() in _SKIP:
+            continue
+        cm = _COL_RE.match(line)
+        if cm:
+            tables[current].append(cm.group(1))
+    return tables
+
+
+def _schema_facts(schema: str) -> str:
+    ids = schema_identifiers(schema)
+    if not ids:
+        return ""
+    lines = [f"- {t}({', '.join(cols)})" for t, cols in ids.items() if cols]
+    return "The database has ONLY these tables and columns:\n" + "\n".join(lines)
+
+
+def build_correction_messages(schema: str, question: str, bad_sql: str,
+                              error: str) -> list[dict]:
+    """Self-correction prompt: the model's previous query failed to execute.
+
+    Keeps the original system/task framing (so it stays in-distribution with
+    training) and appends the failed attempt + the SQLite error, PLUS the exact
+    valid table/column names parsed from the schema — so the model can't keep
+    inventing or pluralising identifiers. Also nudges it away from needless JOINs
+    (the 1.5B's main failure mode).
+    """
+    facts = _schema_facts(schema)
+    user = (
+        f"{build_user(schema, question)}\n\n"
+        f"Your previous query failed with a database error.\n"
+        f"Previous query: {bad_sql}\n"
+        f"Error: {error}\n\n"
+        f"{facts}\n\n"
+        f"Use ONLY the exact table and column names listed above — do not invent, "
+        f"pluralise, or rename them. Prefer the simplest query and avoid "
+        f"unnecessary JOINs. Then write a corrected SQLite query. "
+        f"Respond with only the SQL query."
+    )
+    return [
+        {"role": "system", "content": SYSTEM_PROMPT},
+        {"role": "user", "content": user},
+    ]