Add schemagate demo app

README.md

@@ -1,8 +1,8 @@
 ---
-title: Schemagate
-emoji: 🐨
-colorFrom: yellow
-colorTo: indigo
+title: schemagate
+emoji: 🔒
+colorFrom: green
+colorTo: gray
 sdk: gradio
 sdk_version: 6.26.0
 python_version: '3.12'
@@ -10,6 +10,34 @@ app_file: app.py
 pinned: false
 license: apache-2.0
 short_description: Identity-scoped schema selection for text-to-SQL
+tags:
+  - text-to-sql
+  - nl2sql
+  - rag
+  - sql
+  - security
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# schemagate
+
+Picks the handful of tables a text-to-SQL model needs, and filters them by who is
+asking — **before** the model sees anything.
+
+Schema selection runs before the query runs, so it runs before row-level security
+can act. A selector that is not identity-aware hands the model a table the caller
+cannot read: the SQL is correct, RLS filters every row, and the user is told
+*no records found*. A wrong answer in a confident tone, not an access-denied message.
+
+This Space runs the real selector over a bundled 42-object demo schema.
+No database, no API key, no model call — BM25 plus a hashed embedder, offline.
+`hr_compensation` is restricted to the `payroll` role: change the roles box and
+watch it appear and disappear from the prompt.
+
+```
+pip install schemagate
+schemagate demo "which customers owe us money"
+```
+
+- Source: https://github.com/ashishsinha1602/schemagate
+- PyPI: https://pypi.org/project/schemagate/
+- Apache-2.0. Certified live on Oracle Autonomous Database 26ai and PostgreSQL 16.

app.py

@@ -0,0 +1,106 @@
+"""schemagate on Hugging Face Spaces.
+
+Two questions this page answers, without a database and without a model:
+  1. What does the selector actually send to the LLM?
+  2. What happens to a restricted table when the caller lacks the role?
+"""
+from __future__ import annotations
+
+import gradio as gr
+
+from schemagate import Catalog, Principal
+from schemagate.demo_schema import HINTS, create_demo_db
+
+CAT = Catalog().bootstrap(create_demo_db())
+for _table, _text in HINTS.items():
+    CAT.hint(_table, _text)
+CAT.restrict("hr_compensation", ["payroll"])
+
+FULL_DDL = "\n\n".join(d.render_ddl() for d in CAT.objects())
+FULL_TOKENS = max(1, len(FULL_DDL) // 4)          # ~4 chars per token
+OBJECTS = len(CAT)
+
+EXAMPLES = [
+    ["which customers owe us money", "demo:analyst", ""],
+    ["salary and pay grade by employee", "okta:jdoe", ""],
+    ["salary and pay grade by employee", "okta:hr", "payroll"],
+    ["things we are running out of", "demo:analyst", ""],
+    ["total revenue by month last year", "demo:analyst", ""],
+]
+
+
+def run(question: str, subject: str, roles: str, top_k: int):
+    question = (question or "").strip()
+    if not question:
+        return "Ask something.", "", ""
+
+    role_set = {r.strip() for r in (roles or "").split(",") if r.strip()}
+    principal = Principal(subject or "demo:analyst", roles=role_set)
+    sel = CAT.select(question, top_k=int(top_k), principal=principal)
+
+    fragment = sel.prompt_fragment()
+    tokens = max(1, len(fragment) // 4)
+    cut = 100 - round(tokens / FULL_TOKENS * 100)
+
+    picked = "\n".join(f"- `{n}`" for n in sel.table_names) or "_nothing matched_"
+    restricted = any(n.split(".")[-1] == "hr_compensation" for n in sel.table_names)
+    note = (
+        "`hr_compensation` **is** in the selection — this caller holds `payroll`."
+        if restricted
+        else "`hr_compensation` is **absent**: not ranked low, not present. Its name "
+             "does not appear anywhere in the text below."
+    )
+
+    summary = (
+        f"**{len(sel.table_names)} of {OBJECTS} objects** for "
+        f"`{principal.subject}` roles={sorted(role_set) or '—'}\n\n"
+        f"{picked}\n\n{note}\n\n"
+        f"**{tokens} tokens** in the prompt fragment, against **{FULL_TOKENS}** "
+        f"for the whole schema — a {cut}% cut. The selector never called a model "
+        f"to decide this."
+    )
+    return summary, fragment, sel.explain()
+
+
+with gr.Blocks(title="schemagate", theme=gr.themes.Soft()) as demo:
+    gr.Markdown(
+        "# schemagate\n"
+        "### Identity-scoped schema selection for text-to-SQL\n\n"
+        "Schema selection happens **before** the query runs — so it happens before "
+        "row-level security can act. A selector that is not identity-aware hands the "
+        "model a table the caller cannot read; the SQL is correct, RLS filters every "
+        "row, and the user is told *no records found*. That is a wrong answer in a "
+        "confident tone, not an access-denied message.\n\n"
+        f"This page runs the real selector over a bundled {OBJECTS}-object schema. "
+        "No database, no API key, no model call — BM25 plus a hashed embedder, offline. "
+        "`hr_compensation` is restricted to the `payroll` role: change the roles box "
+        "and watch it appear and disappear."
+    )
+    with gr.Row():
+        with gr.Column(scale=3):
+            question = gr.Textbox(label="Question", value="salary and pay grade by employee")
+        with gr.Column(scale=2):
+            subject = gr.Textbox(label="Caller", value="okta:jdoe")
+            roles = gr.Textbox(label="Roles (comma-separated)", placeholder="payroll")
+            top_k = gr.Slider(1, 12, value=6, step=1, label="Tables to select")
+    go = gr.Button("Select", variant="primary")
+
+    out = gr.Markdown()
+    with gr.Accordion("Prompt fragment — exactly what the model would receive", open=True):
+        fragment = gr.Code(label="", language="sql")
+    with gr.Accordion("Why these tables", open=False):
+        explain = gr.Code(label="")
+
+    gr.Examples(EXAMPLES, inputs=[question, subject, roles])
+    gr.Markdown(
+        "`pip install schemagate` · "
+        "[GitHub](https://github.com/ashishsinha1602/schemagate) · "
+        "[PyPI](https://pypi.org/project/schemagate/) · Apache-2.0\n\n"
+        "Certified live on Oracle Autonomous Database 26ai and PostgreSQL 16."
+    )
+
+    go.click(run, [question, subject, roles, top_k], [out, fragment, explain])
+    question.submit(run, [question, subject, roles, top_k], [out, fragment, explain])
+
+if __name__ == "__main__":
+    demo.launch()

requirements.txt

@@ -0,0 +1 @@
+schemagate>=0.1.8