sqljev 0.1.0__py3-none-any.whl

sqljev/__init__.py

@@ -0,0 +1,6 @@
+"""sqljev: ask your SQL rows questions in plain language, answered by Laya (open weights) or Jev."""
+from .core import (BACKENDS, FUNCTIONS, Jev, JevError, __version__, default_engine, laya_question,
+                   make_config, to_row_json)
+
+__all__ = ["BACKENDS", "FUNCTIONS", "Jev", "JevError", "__version__", "default_engine", "laya_question",
+           "make_config", "to_row_json"]

sqljev/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+main()

sqljev/aws_lambda.py

@@ -0,0 +1,16 @@
+"""AWS Lambda handler for Redshift Lambda UDFs (CREATE EXTERNAL FUNCTION ... LAMBDA 'sqljev').
+
+Handler: sqljev.aws_lambda.handler. Configure with SQLJEV_* environment variables on the function, e.g.
+SQLJEV_BACKEND=gateway + SQLJEV_API_URL=https://your-gateway/v1/eval, or SQLJEV_BACKEND=jev + TYPESAFE_API_KEY.
+The engine (and its answer cache) lives as long as the Lambda container does.
+"""
+import json
+
+from .core import default_engine
+from .gateway import handle_redshift
+
+
+def handler(event, context=None):
+    if isinstance(event, (str, bytes)):
+        event = json.loads(event)
+    return json.dumps(handle_redshift(default_engine(), event))

sqljev/cli.py

@@ -0,0 +1,516 @@
+"""sqljev command line: plain-language questions over any SQLAlchemy database, the gateway, and the
+fine-tuning loop (dataset -> fine-tune Laya -> eval).
+
+  sqljev query URL "SELECT * FROM tickets" --where "the customer is angry" --limit 20
+  sqljev query URL "SELECT * FROM tickets" --rank "the customer is angry" --limit 10
+  sqljev query URL "SELECT * FROM tickets" --choice "which team?" --options billing,technical,sales
+  sqljev materialize URL "SELECT id, body FROM tickets" --key id --prob "the customer is angry" --into t_angry
+  sqljev dataset URL "SELECT * FROM tickets" --label team --choice "which team?" -o tickets.jsonl
+  sqljev eval tickets.test.jsonl
+  sqljev gateway --port 8765
+"""
+import argparse
+import csv
+import hashlib
+import json
+import sys
+import time
+
+from . import core
+from .core import Jev, JevError, check_question, laya_question, to_row_json
+
+
+# ---------------------------------------------------------------- database access (SQLAlchemy)
+
+def _engine(url):
+    try:
+        import sqlalchemy
+    except ImportError:
+        raise JevError("sqljev: database access needs SQLAlchemy: pip install 'sqljev[db]'")
+    return sqlalchemy.create_engine(url)
+
+
+def stream_rows(url, sql, chunk=1000):
+    """Rows as dicts, streamed with a server-side cursor where the driver supports it."""
+    import sqlalchemy
+    eng = _engine(url)
+    with eng.connect() as conn:
+        res = conn.execution_options(stream_results=True, yield_per=chunk).execute(sqlalchemy.text(sql))
+        for m in res.mappings():
+            yield dict(m)
+
+
+def _model_view(columns, exclude=()):
+    """The part of a row the model sees: --columns selects, the label column is always excluded."""
+    cols = [c.strip() for c in columns.split(",")] if columns else None
+
+    def view(row):
+        return {k: v for k, v in row.items() if (cols is None or k in cols) and k not in exclude}
+    return view
+
+
+# ---------------------------------------------------------------- question selection shared by commands
+
+def _question(a, need=True):
+    picked = [(k, getattr(a, k)) for k in ("where", "rank", "prob", "choice", "score", "noul")
+              if getattr(a, k, None)]
+    if len(picked) != 1:
+        if not need:
+            return None
+        raise JevError("sqljev: give exactly one of --where / --rank / --prob / --choice / --score")
+    mode, text = picked[0]
+    kind = {"choice": "choice", "score": "score"}.get(mode, "noul")
+    opts = a.options if kind == "choice" else getattr(a, "levels", None) if kind == "score" else None
+    if kind == "choice" and opts is None and mode == "choice" and getattr(a, "label", None):
+        return mode, text, kind, None          # dataset: options come from the label column
+    kind, opts = check_question(kind, opts)
+    return mode, text, kind, opts
+
+
+def _settings(a):
+    return {k: getattr(a, k) for k in ("backend", "api_url", "model", "device", "batch_size", "concurrency",
+                                       "max_rows", "max_len") if getattr(a, k, None) is not None} | \
+        ({"drop_nulls": False} if getattr(a, "keep_nulls", False) else {})
+
+
+def _value(kind, a, opts):
+    if a is None:
+        return None
+    if kind == "noul":
+        return a["noul"]
+    if kind == "choice":
+        return a["choice"]
+    return a["score"]
+
+
+# ---------------------------------------------------------------- output
+
+def _fmt(v, width=40):
+    if isinstance(v, float):
+        return "%.3f" % v
+    s = "" if v is None else str(v)
+    s = s.replace("\n", " ")
+    return s if len(s) <= width else s[:width - 1] + "…"
+
+
+def write_rows(rows, fmt, out=None):
+    out = out or sys.stdout
+    rows = list(rows)
+    if not rows:
+        print("(0 rows)", file=sys.stderr)
+        return
+    cols = list(rows[0].keys())
+    if fmt == "jsonl":
+        for r in rows:
+            out.write(json.dumps(r, default=str, ensure_ascii=False) + "\n")
+    elif fmt == "csv":
+        w = csv.DictWriter(out, fieldnames=cols)
+        w.writeheader()
+        w.writerows(rows)
+    else:
+        cells = [[_fmt(r.get(c)) for c in cols] for r in rows]
+        widths = [max(len(c), *(len(row[i]) for row in cells)) for i, c in enumerate(cols)]
+        out.write(" | ".join(c.ljust(w) for c, w in zip(cols, widths)) + "\n")
+        out.write("-+-".join("-" * w for w in widths) + "\n")
+        for row in cells:
+            out.write(" | ".join(v.ljust(w) for v, w in zip(row, widths)) + "\n")
+        print("(%d row%s)" % (len(rows), "" if len(rows) == 1 else "s"), file=sys.stderr)
+
+
+# ---------------------------------------------------------------- commands
+
+def cmd_query(a):
+    mode, text, kind, opts = _question(a)
+    jev = Jev(**_settings(a))
+    view = _model_view(a.columns)
+    rows = stream_rows(a.url, a.sql)
+    col = {"where": "jev_prob", "rank": "jev_prob", "prob": "jev_prob", "choice": "jev_choice",
+           "score": "jev_score"}[mode]
+    t0 = time.time()
+    if mode == "where":
+        # Streaming: rows are judged in order with a bounded read-ahead, so --limit stops the scan early.
+        threshold = a.threshold if a.threshold is not None else jev.cfg["threshold"]
+
+        def passing():
+            n = 0
+            for row, ans in jev.evaluate_iter(rows, text, kind, opts, key=view):
+                p = ans["noul"]
+                if p >= threshold:
+                    yield {**row, col: p}
+                    n += 1
+                    if a.limit and n >= a.limit:
+                        return
+        write_rows(passing(), a.format)
+    else:
+        all_rows = list(rows)
+        answers = jev.evaluate([view(r) for r in all_rows], text, kind, opts)
+        out = [{**r, col: _value(kind, ans, opts)} for r, ans in zip(all_rows, answers)]
+        if mode == "rank" or (mode == "score" and a.sort):
+            out.sort(key=lambda r: -(r[col] or 0))
+        write_rows(out[:a.limit] if a.limit else out, a.format)
+    _report(jev, t0, a)
+
+
+def cmd_materialize(a):
+    """Judge every row and write (key, value, answer) into a table, joinable in any database."""
+    import sqlalchemy as sa
+    mode, text, kind, opts = _question(a)
+    jev = Jev(**_settings(a))
+    view = _model_view(a.columns)
+    rows = list(stream_rows(a.url, a.sql))
+    if rows and a.key not in rows[0]:
+        raise JevError("sqljev: key column %r is not in the query result" % a.key)
+    t0 = time.time()
+    answers = jev.evaluate([view(r) for r in rows], text, kind, opts)
+    col = "jev_" + ("choice" if kind == "choice" else "score" if kind == "score" else "prob")
+    key_type = sa.BigInteger() if rows and isinstance(rows[0][a.key], int) else sa.String(255)
+    eng = _engine(a.url)
+    meta = sa.MetaData()
+    schema, _, name = a.into.rpartition(".")
+    table = sa.Table(name, meta, sa.Column(a.key, key_type, primary_key=True),
+                     sa.Column(col, sa.String(255) if kind == "choice" else sa.Float()),
+                     sa.Column("jev_answer", sa.Text()), schema=schema or None)
+    with eng.begin() as conn:
+        if a.replace:
+            table.drop(conn, checkfirst=True)
+        table.create(conn, checkfirst=True)
+        payload = [{a.key: r[a.key], col: _value(kind, ans, opts), "jev_answer": json.dumps(ans)}
+                   for r, ans in zip(rows, answers)]
+        for i in range(0, len(payload), 1000):
+            conn.execute(table.insert(), payload[i:i + 1000])
+    print("sqljev: wrote %d rows to %s (%s)" % (len(rows), a.into, col), file=sys.stderr)
+    _report(jev, t0, a)
+
+
+def _truthy(v):
+    if isinstance(v, bool):
+        return v
+    s = str(v).strip().lower()
+    if s in ("1", "true", "t", "yes", "y"):
+        return True
+    if s in ("0", "false", "f", "no", "n"):
+        return False
+    raise JevError("sqljev: label %r is not a boolean" % (v,))
+
+
+def cmd_dataset(a):
+    """Labelled SQL rows -> Laya training/eval data, using exactly the state and question sqljev asks at
+    query time, so a checkpoint fine-tuned on it sees what it will be asked."""
+    mode, text, kind, opts = _question(a)
+    view = _model_view(a.columns, exclude={a.label})
+    rows = list(stream_rows(a.url, a.sql))
+    if not rows:
+        raise JevError("sqljev: the query returned no rows")
+    if a.label not in rows[0]:
+        raise JevError("sqljev: label column %r is not in the query result" % a.label)
+    if kind == "choice" and opts is None:
+        opts = sorted({str(r[a.label]) for r in rows if r[a.label] is not None})
+        kind, opts = check_question(kind, opts)
+    q = {"q": laya_question(kind, text, opts)}
+    base = a.output[:-6] if a.output.endswith(".jsonl") else a.output
+    outs = {"train": open(base + ".train.jsonl", "w"), "test": open(base + ".test.jsonl", "w")} \
+        if a.test_fraction else {"all": open(a.output, "w")}
+    counts = {k: 0 for k in outs}
+    skipped = 0
+    for r in rows:
+        lab = r[a.label]
+        if lab is None:
+            skipped += 1
+            continue
+        if kind == "noul":
+            expected = _truthy(lab)
+            gold = {"label": "true" if expected else "false",
+                    "probabilities": {"true": float(expected), "false": float(not expected)}}
+        elif kind == "choice":
+            expected = str(lab)
+            if expected not in opts:
+                skipped += 1
+                continue
+            gold = {"label": expected, "probabilities": {o: float(o == expected) for o in opts}}
+        else:
+            idx = opts.index(str(lab)) if str(lab) in opts else int(lab)
+            expected = idx
+            gold = {"label": idx, "probabilities": {str(i): float(i == idx) for i in range(len(opts))}}
+        state = json.loads(to_row_json(view(r), not a.keep_nulls))
+        rid = hashlib.sha1(json.dumps(state, sort_keys=True, default=str).encode()).hexdigest()[:16]
+        split = "all"
+        if a.test_fraction:
+            split = "test" if int(rid[:8], 16) / 0xFFFFFFFF < a.test_fraction else "train"
+        if a.format == "typed-decisions":
+            rec = {"id": rid, "workflow": a.workflow, "state": json.dumps(state, ensure_ascii=False),
+                   "questions": json.dumps(q), "gold": json.dumps({"q": gold})}
+        else:
+            rec = {"state": state, "questions": q, "expected": {"q": expected}, "tags": [a.workflow]}
+        outs[split].write(json.dumps(rec, ensure_ascii=False, default=str) + "\n")
+        counts[split] += 1
+    for f in outs.values():
+        f.close()
+    print("sqljev: %s%s" % (", ".join("%s %d" % kv for kv in counts.items()),
+                             ", skipped %d (no/unknown label)" % skipped if skipped else ""), file=sys.stderr)
+
+
+def cmd_eval(a):
+    """Accuracy of the configured backend / checkpoint on a dataset file (from `sqljev dataset`)."""
+    from .finetune import accuracy
+    s = _settings(a)
+    res = accuracy(a.file, **s)
+    print(json.dumps({"backend": s.get("backend", "local"), "model": s.get("model"), **res}))
+    if a.min_accuracy is not None and res["accuracy"] < a.min_accuracy:
+        sys.exit(1)
+
+
+def cmd_finetune(a):
+    from .finetune import finetune
+    finetune(a.train, a.out, base=a.base, epochs=a.epochs, micro_batch=a.micro_batch, grad_accum=a.grad_accum,
+             train_layers=a.train_layers, device=a.device, seed=a.seed, log=lambda m: print(m, file=sys.stderr, flush=True))
+    print("sqljev: use it with --model %s (or SQLJEV_MODEL=%s)" % (a.out, a.out), file=sys.stderr)
+
+
+def cmd_publish(a):
+    import os
+    from .finetune import publish
+    metrics = json.loads(a.metrics) if a.metrics else None
+    url = publish(a.dir, a.repo, token=os.environ.get("HF_TOKEN"), private=not a.public, metrics=metrics)
+    print("sqljev: published %s\nsqljev: every database can now use SQLJEV_MODEL=%s" % (url, a.repo), file=sys.stderr)
+
+
+def cmd_gateway(a):
+    from .gateway import serve
+    serve(a.host, a.port, Jev(**_settings(a)), certfile=a.certfile, keyfile=a.keyfile)
+
+
+def _quote(dialect, ident):
+    q = {"mssql": ("[", "]"), "mysql": ("`", "`"), "mariadb": ("`", "`")}.get(dialect, ('"', '"'))
+    return q[0] + ident.replace(q[1], q[1] * 2) + q[1]
+
+
+def _lit(s):
+    return "'" + s.replace("'", "''") + "'"
+
+
+class _Dialect:
+    """What `sqljev judge` needs from each database: resolve the source, a row -> JSON expression computed by
+    the database itself, and the jev.answers / jev_answers statements of sql/<db>/install.sql."""
+
+    def __init__(self, conn, source, columns):
+        import sqlalchemy as sa
+        self.sa, self.conn, self.name = sa, conn, conn.dialect.name
+        cols = [c.strip() for c in columns.split(",")] if columns else None
+        if self.name == "mssql":
+            self.table = conn.execute(sa.text(
+                "SELECT QUOTENAME(OBJECT_SCHEMA_NAME(OBJECT_ID(:s))) + N'.' + QUOTENAME(OBJECT_NAME(OBJECT_ID(:s)))"),
+                {"s": source}).scalar()
+            inner = ", ".join("t." + _quote(self.name, c) for c in cols) if cols else "t.*"
+            self.row = "(SELECT %s FOR JSON PATH, WITHOUT_ARRAY_WRAPPER)" % inner
+            self.hash, self.answers, self.qkey = "jev.row_hash(%s)", "jev.answers", "SELECT jev.question_key(:q, :k, :o)"
+        elif self.name == "postgresql":
+            self.table = conn.execute(sa.text("SELECT to_regclass(:s)::text"), {"s": source}).scalar()
+            self.row = ("jsonb_build_object(%s)" % ", ".join("%s, t.%s" % (_lit(c), _quote(self.name, c)) for c in cols)
+                        if cols else "to_jsonb(t)")
+            self.hash, self.answers = "jev.row_hash(%s)", "jev.answers"
+            self.qkey = "SELECT jev.question_key(:q, :k, CAST(:o AS text[]))"
+        elif self.name in ("mysql", "mariadb"):
+            schema, _, tbl = source.rpartition(".")
+            found = conn.execute(sa.text(
+                "SELECT COLUMN_NAME FROM information_schema.COLUMNS WHERE TABLE_SCHEMA = COALESCE(:sc, DATABASE()) "
+                "AND TABLE_NAME = :t ORDER BY ORDINAL_POSITION"), {"sc": schema or None, "t": tbl}).scalars().all()
+            self.table = ".".join(_quote(self.name, x) for x in ([schema] if schema else []) + [tbl]) if found else None
+            use = [c for c in found if c in cols] if cols else found
+            self.row = "JSON_OBJECT(%s)" % ", ".join("%s, t.%s" % (_lit(c), _quote(self.name, c)) for c in use)
+            self.hash, self.answers, self.qkey = "jev_row_hash(%s)", "jev_answers", "SELECT jev_question_key(:q, :k, :o)"
+        else:
+            raise JevError("sqljev: judge supports SQL Server, PostgreSQL, MySQL and MariaDB (got %s); for other "
+                           "databases use `sqljev materialize`" % self.name)
+        if not self.table:
+            raise JevError("sqljev: %r is not a table or view" % source)
+
+    def question_key(self, text, kind, opts):
+        o = opts if self.name == "postgresql" else (json.dumps(opts) if opts else None)
+        return self.conn.execute(self.sa.text(self.qkey), {"q": text, "k": kind, "o": o}).scalar()
+
+    def pending(self, qkey, where):
+        """(row_hash, row_json) for rows with no answer yet, de-duplicated by content."""
+        sql = ("SELECT %s AS h, x.j AS j FROM (SELECT %s AS j FROM %s AS t%s) AS x WHERE NOT EXISTS "
+               "(SELECT 1 FROM %s AS a WHERE a.question_key = :qk AND a.row_hash = %s)"
+               % (self.hash % "x.j", self.row, self.table, " WHERE " + where if where else "", self.answers,
+                  self.hash % "x.j"))
+        todo = {}
+        for h, j in self.conn.execute(self.sa.text(sql), {"qk": qkey}):
+            todo.setdefault(bytes(h), j if isinstance(j, str) else json.dumps(j))
+        return todo
+
+    def store(self, qkey, pairs):
+        sql = {"mssql": "INSERT jev.answers (question_key, row_hash, answer) VALUES (:qk, :h, :a)",
+               "postgresql": "INSERT INTO jev.answers (question_key, row_hash, answer) VALUES (:qk, :h, CAST(:a AS jsonb))"
+                             " ON CONFLICT DO NOTHING"}.get(
+            self.name, "INSERT IGNORE INTO jev_answers (question_key, row_hash, answer) VALUES (:qk, :h, :a)")
+        rows = [{"qk": qkey, "h": h, "a": json.dumps(a)} for h, a in pairs]
+        for i in range(0, len(rows), 500):
+            self.conn.execute(self.sa.text(sql), rows[i:i + 500])
+
+    def usage(self, mode, text, opts):
+        fn = ("jev." if self.name in ("mssql", "postgresql") else "jev_") + \
+            {"choice": "choice", "score": "score"}.get(mode, "prob")
+        n = "N" if self.name == "mssql" else ""
+        args = [self.row, n + _lit(text)]
+        if opts:
+            args.append("ARRAY[%s]" % ", ".join(_lit(o) for o in opts) if self.name == "postgresql"
+                        else n + _lit(json.dumps(opts)))
+        return "%s(%s)" % (fn, ", ".join(args))
+
+
+def cmd_judge(a):
+    """Judge every row of a table that has no answer yet and store the answers in the database, where the
+    lookup functions of sql/<db>/install.sql read them. The database computes each row's JSON and hash itself,
+    so its functions find exactly these answers, and a row edited later is judged again on the next run."""
+    mode, text, kind, opts = _question(a)
+    jev = Jev(**_settings(a))
+    t0 = time.time()
+    with _engine(a.url).begin() as conn:
+        d = _Dialect(conn, a.source, a.columns)
+        qkey = d.question_key(text, kind, opts)
+        todo = d.pending(qkey, a.filter)
+        answers = jev.evaluate(list(todo.values()), text, kind, opts)
+        d.store(qkey, zip(todo, answers))
+    print("sqljev: judged %d new rows of %s" % (len(todo), d.table), file=sys.stderr)
+    print("sqljev: read them with %s" % d.usage(mode, text, opts), file=sys.stderr)
+    _report(jev, t0, a)
+
+
+def _report(jev, t0, a):
+    if a.stats:
+        s = jev.stats()
+        s["seconds"] = round(time.time() - t0, 2)
+        print("sqljev: " + json.dumps(s), file=sys.stderr)
+
+
+# ---------------------------------------------------------------- argument parsing
+
+def _common(p):
+    g = p.add_argument_group("model")
+    g.add_argument("--backend", choices=core.BACKENDS, help="default: local (Laya in-process); env SQLJEV_BACKEND")
+    g.add_argument("--api-url", help="gateway / laya-serve / Jev endpoint")
+    g.add_argument("--model", help="Laya checkpoint (english, multilingual, typed-decisions), a fine-tuned "
+                                   "checkpoint directory or Hub id, or a Jev model id")
+    g.add_argument("--device", help="cpu, cuda, mps (local backend)")
+    g.add_argument("--batch-size", type=int, help="rows per forward pass / request")
+    g.add_argument("--concurrency", type=int)
+    g.add_argument("--max-len", type=int, help="Laya token budget per row (multilingual reads up to 8192)")
+    g.add_argument("--max-rows", type=int, help="spend guard: refuse to send more rows than this")
+    g.add_argument("--keep-nulls", action="store_true", help="send NULL columns to the model too")
+    g.add_argument("--stats", action="store_true", help="print engine stats to stderr")
+
+
+def _questions(p, dataset=False):
+    g = p.add_argument_group("question (exactly one)")
+    if dataset:
+        g.add_argument("--noul", metavar="CONDITION", help="yes/no condition; label column holds true/false")
+    else:
+        g.add_argument("--where", metavar="CONDITION", help="keep rows that satisfy the condition (streams)")
+        g.add_argument("--rank", metavar="CONDITION", help="order rows by probability, most likely first")
+        g.add_argument("--prob", metavar="CONDITION", help="add jev_prob for every row")
+    g.add_argument("--choice", metavar="QUESTION", help="classify each row into one of --options")
+    g.add_argument("--score", metavar="QUESTION", help="rate each row along ordered --levels")
+    g.add_argument("--options", type=core.parse_options, help="comma list or JSON array")
+    g.add_argument("--levels", type=core.parse_options, help="comma list or JSON array, lowest first")
+    p.add_argument("--columns", help="comma list of columns the model sees (default: all)")
+
+
+def main(argv=None):
+    p = argparse.ArgumentParser(prog="sqljev", description="Ask your SQL rows questions in plain language.")
+    p.add_argument("--version", action="version", version="sqljev " + core.__version__)
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    q = sub.add_parser("query", help="run a SELECT and filter / rank / classify its rows")
+    q.add_argument("url", help="SQLAlchemy URL, e.g. postgresql://..., mssql+pyodbc://..., snowflake://...")
+    q.add_argument("sql")
+    _questions(q)
+    q.add_argument("--threshold", type=float)
+    q.add_argument("--limit", type=int)
+    q.add_argument("--sort", action="store_true", help="with --score: highest first")
+    q.add_argument("--format", choices=("table", "csv", "jsonl"), default="table")
+    _common(q)
+    q.set_defaults(fn=cmd_query)
+
+    m = sub.add_parser("materialize", help="write judgments into a table, keyed by a column")
+    m.add_argument("url")
+    m.add_argument("sql")
+    m.add_argument("--key", required=True)
+    m.add_argument("--into", required=True, help="table name ([schema.]table)")
+    m.add_argument("--replace", action="store_true")
+    _questions(m)
+    _common(m)
+    m.set_defaults(fn=cmd_materialize)
+
+    d = sub.add_parser("dataset", help="labelled rows -> Laya fine-tuning / eval JSONL")
+    d.add_argument("url")
+    d.add_argument("sql")
+    d.add_argument("--label", required=True, help="column holding the ground truth (never shown to the model)")
+    d.add_argument("-o", "--output", required=True)
+    d.add_argument("--format", choices=("laya-evals", "typed-decisions"), default="laya-evals")
+    d.add_argument("--test-fraction", type=float, default=0.0, help="write OUTPUT.train/.test.jsonl")
+    d.add_argument("--workflow", default="sql")
+    d.add_argument("--keep-nulls", action="store_true")
+    _questions(d, dataset=True)
+    d.set_defaults(fn=cmd_dataset)
+
+    e = sub.add_parser("eval", help="accuracy of a backend / checkpoint on a dataset file")
+    e.add_argument("file")
+    e.add_argument("--min-accuracy", type=float)
+    _common(e)
+    e.set_defaults(fn=cmd_eval)
+
+    f = sub.add_parser("finetune", help="fine-tune Laya on a `sqljev dataset` file (one GPU)")
+    f.add_argument("train", help="training JSONL from `sqljev dataset`")
+    f.add_argument("--out", required=True, help="output checkpoint directory")
+    f.add_argument("--base", default="convaiinnovations/laya",
+                   help="english (default), multilingual, typed-decisions, a Hub id or a local checkpoint")
+    f.add_argument("--epochs", type=int, default=3)
+    f.add_argument("--micro-batch", type=int, default=8)
+    f.add_argument("--grad-accum", type=int, default=8)
+    f.add_argument("--train-layers", type=int, help="low-memory mode: train only the top N encoder layers + head")
+    f.add_argument("--device")
+    f.add_argument("--seed", type=int, default=0)
+    f.set_defaults(fn=cmd_finetune)
+
+    pb = sub.add_parser("publish", help="upload a fine-tuned checkpoint to the Hugging Face Hub (HF_TOKEN)")
+    pb.add_argument("dir")
+    pb.add_argument("--repo", required=True, help="e.g. your-org/laya-tickets")
+    pb.add_argument("--public", action="store_true", help="default: private")
+    pb.add_argument("--metrics", help='JSON, e.g. \'{"base": 0.41, "finetuned": 0.93}\'')
+    pb.set_defaults(fn=cmd_publish)
+
+    g = sub.add_parser("gateway", help="serve the HTTP gateway for SQL Server, Snowflake, BigQuery, Redshift")
+    g.add_argument("--host", default="127.0.0.1")
+    g.add_argument("--port", type=int, default=8765)
+    g.add_argument("--certfile", help="serve HTTPS with this certificate (PEM)")
+    g.add_argument("--keyfile", help="private key for --certfile")
+    _common(g)
+    g.set_defaults(fn=cmd_gateway)
+
+    s = sub.add_parser("judge", help="judge a table into jev answers (SQL Server, PostgreSQL, MySQL, MariaDB)")
+    s.add_argument("url", help="mssql+pymssql://..., postgresql://..., mysql+pymysql://..., mariadb+pymysql://...")
+    s.add_argument("--source", required=True, help="table or view, e.g. dbo.tickets / public.tickets / tickets")
+    s.add_argument("--where", dest="filter", help="filter in the database's SQL, applied before judging")
+    s.add_argument("--columns", help="comma list of columns the model sees (default: all)")
+    g2 = s.add_argument_group("question (exactly one)")
+    g2.add_argument("--prob", metavar="CONDITION")
+    g2.add_argument("--choice", metavar="QUESTION")
+    g2.add_argument("--score", metavar="QUESTION")
+    g2.add_argument("--options", type=core.parse_options)
+    g2.add_argument("--levels", type=core.parse_options)
+    _common(s)
+    s.set_defaults(fn=cmd_judge)
+
+    a = p.parse_args(argv)
+    try:
+        a.fn(a)
+    except JevError as e:
+        print(str(e), file=sys.stderr)
+        sys.exit(2)
+    except BrokenPipeError:
+        pass
+
+
+if __name__ == "__main__":
+    main()