"""Gradio interface: settings on the left, one stage at a time on the right."""
from __future__ import annotations
from pathlib import Path
import gradio as gr
from . import engine, views
MODE_PLAIN = "Language model only"
MODE_MARKED = "With SynthID watermark"
MODE_COMPARE = "Both, side by side"
MODES = {MODE_PLAIN: "plain", MODE_MARKED: "marked", MODE_COMPARE: "compare"}
UPLOAD_KEY = "Upload a key file"
N_SHOW = 10 # candidates shown in every ranked list
APPEND_SECONDS = 1.35 # Append moves on to the next token after this long
SAMPLE_SECONDS = 3.4 # Sample plays its "chosen token" animation, then moves to Append
CUSTOM_PROMPT = "Custom prompt"
GARDEN = {
"name": "Garden (slide example)",
"prompt": "In spring, the garden was filled with roses and butterflies. The flowers were",
"max_new_tokens": 30, "temperature": 0.5, "top_k": 40, "seed": 7,
}
TITLES = {
"plain": "How a language model writes",
"marked": "How SynthID Text watermarks a language model",
"compare": "One prompt, with and without the SynthID watermark",
}
STYLE = (Path(__file__).with_name("style.css")).read_text(encoding="utf-8")
# Arrow keys and Page Up / Page Down (presentation remotes) step through the run.
HEAD = """
"""
_BLUE = gr.themes.Color(
c50="#eef5fd", c100="#cde2fb", c200="#9ec5f4", c300="#6da7ec", c400="#3987e5",
c500="#2a78d6", c600="#256abf", c700="#1c5cab", c800="#184f95", c900="#104281",
c950="#0d366b", name="sx_blue",
)
THEME = gr.themes.Base(
primary_hue=_BLUE, secondary_hue=_BLUE, neutral_hue=gr.themes.colors.stone,
radius_size=gr.themes.sizes.radius_md, text_size=gr.themes.sizes.text_lg,
font=["Segoe UI Variable Text", "Segoe UI", "system-ui", "-apple-system", "sans-serif"],
font_mono=["Cascadia Mono", "Cascadia Code", "Consolas", "ui-monospace", "monospace"],
)
def _html(value: str = "", **kwargs) -> gr.HTML:
"""An HTML slot styled only by style.css."""
classes = ["sx-host"] + kwargs.pop("elem_classes", [])
return gr.HTML(value, padding=False, apply_default_css=False, elem_classes=classes,
**kwargs)
def _presets() -> dict[str, dict]:
presets = {CUSTOM_PROMPT: {}, GARDEN["name"]: GARDEN}
for path in engine.repo_prompt_files():
label = path.stem.replace("_", " ").capitalize()
# Same text as `--prompt "$(cat file)"`: trailing newlines dropped.
presets[label] = {"prompt": path.read_text(encoding="utf-8").rstrip("\n")}
return presets
_MODEL_TAG = "GPT-2" # set by build() from the checkpoints found
_THEME_BUTTON = (
'')
def _title(mode: str) -> str:
"""Page header: brand, title of the current mode, what is running."""
keyed = "" if mode == "plain" else " data-keyed"
tags = f'{_MODEL_TAG}'
if keyed:
tags += 'SynthID Text'
return (
f''
'
'
"Token explorer
"
f'
{TITLES[mode]}
{tags}{_THEME_BUTTON}
'
)
def _empty(models: list[str]) -> str:
if not models:
body = ("No GPT-2 or Gemma checkpoint was found in the local Hugging Face cache. "
"The explorer runs offline, like the command-line demo, so the "
"model has to be cached first. See the README for the command.")
else:
steps = "".join(f"{name}" for name in (
"Tokenize", "Transformer", "Probabilities", "Top-k",
"Sample", "Append"))
return ('
Choose a prompt and press '
f'Generate.
{steps}
')
return f'
{body}
'
def build(llm_only: bool = False) -> gr.Blocks:
"""Create the interface. With ``llm_only`` the watermark controls never appear."""
global _MODEL_TAG
models = engine.cached_models()
kinds = ["GPT-2"] if any("gpt2" in name for name in models) else []
kinds += ["Gemma"] if any("gemma" in name.lower() for name in models) else []
_MODEL_TAG = " · ".join(kinds) or "Language model"
key_files = {path.name: path for path in engine.repo_key_files()}
presets = _presets()
key_choices = list(key_files) + [UPLOAD_KEY]
# ---------------------------------------------------------------- helpers
def resolve_key(choice, upload):
if choice == UPLOAD_KEY:
if not upload:
raise gr.Error("Choose a key file to upload, or pick one of the listed keys.")
return engine.load_key_file(upload, label=Path(upload).name)
if choice not in key_files:
raise gr.Error("No key file selected.")
return engine.load_key_file(key_files[choice])
def key_summary(choice, upload):
"""Only problems are shown here; the key's details are in "Model setup"."""
try:
resolve_key(choice, upload)
except gr.Error:
return ""
except (OSError, ValueError) as error:
return f'
{error}
'
return ""
def current(sess, focus):
if sess["mode"] == "compare":
return sess["marked"] if focus == "marked" else sess["plain"]
return sess["marked"] if sess["mode"] == "marked" else sess["plain"]
def clamp(run, pos):
stages = views.stages_for(run)
stage = pos["stage"] if pos["stage"] in stages else "topk"
return {"t": max(0, min(run.n_steps - 1, pos["t"])), "stage": stage}
def at_end(run, pos):
return pos["t"] == run.n_steps - 1 and pos["stage"] == "append"
def moved(run, pos, delta):
stages = views.stages_for(run)
t, i = pos["t"], stages.index(pos["stage"]) + delta
if i >= len(stages):
t, i = (t + 1, 0) if t < run.n_steps - 1 else (t, len(stages) - 1)
elif i < 0:
t, i = (t - 1, len(stages) - 1) if t > 0 else (t, 0)
return {"t": t, "stage": stages[i]}
def detection_html(sess, run):
if not sess["ended"]:
return views.render_detection_pending()
if sess["mode"] == "compare":
return "".join(
views.render_detection(r.detection, r.new_ids, r.token_text, title)
for r, title in ((sess["plain"], "Without watermark"),
(sess["marked"], "With SynthID watermark")))
return views.render_detection(run.detection, run.new_ids, run.token_text)
def view(sess, pos, focus, auto=True):
"""All updates of the explorer for the current position."""
run = current(sess, focus)
pos = clamp(run, pos)
t, stage = pos["t"], pos["stage"]
stages = views.stages_for(run)
if at_end(run, pos):
sess["ended"] = True
if sess["mode"] == "compare":
tape = views.render_compare(sess["plain"], sess["marked"], t, stage, focus,
sess["ended"])
else:
tape = views.render_tape(run, t, stage)
where = (f'
Token {t + 1} of {run.n_steps}'
f'step {stages.index(stage) + 1} of {len(stages)}
')
panel = views.render_stage(run, t, stage, n_show=N_SHOW)
# On Append, move on to the next token by itself (not when stepping back).
onward = auto and (stage == "sample"
or (stage == "append" and t < run.n_steps - 1))
pause = SAMPLE_SECONDS if stage == "sample" else APPEND_SECONDS
on_mark = run.watermarked and stage in views.WATERMARK_STAGES
detail = views.render_tournament_detail(run, t, N_SHOW) if on_mark else ""
return (
sess, pos, tape, where,
gr.Slider(minimum=1, maximum=max(2, run.n_steps), value=t + 1,
interactive=run.n_steps > 1),
gr.Radio(choices=views.stage_choices(run), value=stage),
panel, detail,
detection_html(sess, run) if run.detection is not None else "",
views.render_run_details(run),
views.render_model_setup(run, t),
gr.Timer(value=pause, active=onward),
)
# ----------------------------------------------------------------- layout
with gr.Blocks(title="SynthID Text explorer", fill_width=True) as demo:
session = gr.State(None)
position = gr.State({"t": 0, "stage": "tokens"})
onward_timer = gr.Timer(APPEND_SECONDS, active=False)
with gr.Sidebar(open=True, width=380):
mode = gr.Radio(list(MODES), value=MODE_PLAIN, label="Show",
visible=not llm_only, elem_id="sx-mode")
with gr.Group(visible=False, elem_id="sx-keys") as key_group:
key_choice = gr.Dropdown(key_choices, value=key_choices[0], label="Key file")
key_upload = gr.File(label="Key file to upload", file_types=[".txt", ".json"],
type="filepath", visible=False)
key_info = _html(key_summary(key_choices[0], None))
preset = gr.Dropdown(list(presets), value=GARDEN["name"], label="Prompt preset")
prompt = gr.Textbox(GARDEN["prompt"], label="Prompt", lines=3)
generate = gr.Button("Generate", variant="primary", interactive=bool(models))
with gr.Accordion("Advanced", open=False, elem_id="sx-advanced"):
model = gr.Dropdown(models, value=models[0] if models else None, label="Model")
max_new = gr.Slider(1, engine.MAX_NEW_TOKENS_UI, value=GARDEN["max_new_tokens"],
step=1, label="Max new tokens")
temperature = gr.Slider(0.05, 1.0, value=GARDEN["temperature"], step=0.05,
label="Temperature")
top_k = gr.Slider(2, 100, value=GARDEN["top_k"], step=1, label="Top-k")
seed = gr.Number(GARDEN["seed"], label="Seed", precision=0, minimum=0)
title = _html(_title("plain"))
empty = _html(_empty(models))
# Inside the explorer, the watermark-only parts stay mounted and
# style.css shows them according to the stage on screen. (In
# Gradio 6.16 a container that starts hidden inside a hidden
# column does not reliably reappear.)
with gr.Column(visible=False, elem_id="sx-explorer") as explorer:
focus = gr.Radio(
[("Without watermark", "plain"), ("With SynthID watermark", "marked")],
value="marked", label="Step through", elem_id="sx-focus")
tape = _html()
with gr.Row(elem_id="sx-controls", equal_height=True):
back = gr.Button("← Back", size="md", min_width=96, elem_id="sx-back")
forward = gr.Button("Next step →", variant="primary", size="md",
min_width=140, elem_id="sx-next")
prev_token = gr.Button("« Previous token", size="md", min_width=150,
elem_id="sx-prev-token",
elem_classes=["sx-token-btn"])
next_token = gr.Button("Next token »", size="md", min_width=130,
elem_id="sx-next-token",
elem_classes=["sx-token-btn"])
where = _html(elem_id="sx-where")
stage = gr.Radio([], label="Steps for this token", elem_id="sx-rail",
show_label=False)
panel = _html()
with gr.Accordion("Layer by layer: every tournament round for this token",
open=False, elem_id="sx-detail-box"):
detail = _html()
with gr.Row(elem_id="sx-jump", equal_height=True):
token = gr.Slider(1, 30, value=1, step=1, label="Generated token", scale=1)
end = gr.Button("End ⇥", size="md", min_width=96, scale=0, elem_id="sx-end")
with gr.Accordion("Detection on the finished text", open=True,
elem_id="sx-detect-box"):
detect = _html()
with gr.Accordion("Run details", open=False):
details = _html()
with gr.Accordion("Model setup", open=False):
setup = _html()
# Always mounted; style.css shows it only when the title says a
# watermark mode is on (a tab that starts hidden cannot be opened
# in Gradio 6.16).
with gr.Accordion("Score a text with the key", open=False, elem_id="sx-score-box"):
score_text = gr.Textbox(label="Text to score", lines=7)
score_btn = gr.Button("Score this text", variant="primary", size="sm",
elem_id="sx-score-btn")
score_out = _html()
view_outputs = [session, position, tape, where, token, stage, panel, detail, detect,
details, setup, onward_timer]
view_inputs = [session, position, focus]
# ---------------------------------------------------------- handlers
def on_mode(label):
kind = MODES[label]
marked = kind != "plain"
return (
_title(kind), gr.Group(visible=marked),
"marked", None, gr.Column(visible=False), gr.HTML(_empty(models), visible=True),
)
mode.input(on_mode, mode, [title, key_group, focus, session, explorer, empty])
def on_preset(name):
chosen = presets.get(name, {})
if "prompt" not in chosen:
return gr.skip(), gr.skip(), gr.skip(), gr.skip(), gr.skip()
return (chosen["prompt"], chosen.get("max_new_tokens", gr.skip()),
chosen.get("temperature", gr.skip()), chosen.get("top_k", gr.skip()),
chosen.get("seed", gr.skip()))
preset.input(on_preset, preset, [prompt, max_new, temperature, top_k, seed])
prompt.input(lambda: CUSTOM_PROMPT, None, preset)
key_choice.input(
lambda choice, upload: (gr.File(visible=choice == UPLOAD_KEY),
key_summary(choice, upload)),
[key_choice, key_upload], [key_upload, key_info])
key_upload.change(key_summary, [key_choice, key_upload], key_info)
def on_generate(label, text, model_name, n_tokens, temp, k, seed_value,
choice, upload, progress=gr.Progress()):
kind = "plain" if llm_only else MODES[label]
if not model_name:
raise gr.Error("No cached model to run.")
settings = dict(model=model_name, max_new_tokens=n_tokens, temperature=temp,
top_k=k, seed=0 if seed_value is None else seed_value)
sess = {"mode": kind, "plain": None, "marked": None, "ended": False}
try:
key = resolve_key(choice, upload) if kind != "plain" else None
progress(0.1, desc="Loading the model")
engine.get_bundle(model_name)
if kind in ("plain", "compare"):
progress(0.3, desc="Generating")
sess["plain"] = engine.generate(text, watermarked=False, key=key, **settings)
if kind in ("marked", "compare"):
progress(0.6, desc="Generating with the watermark")
sess["marked"] = engine.generate(text, watermarked=True, key=key, **settings)
except (OSError, ValueError, RuntimeError) as error:
raise gr.Error(str(error)) from error
run = sess["marked"] or sess["plain"]
start_at = {"t": 0, "stage": "tokens"}
return (
*view(sess, start_at, "marked"),
gr.Column(visible=True), gr.HTML(visible=False), "marked",
)
generate.click(
on_generate,
[mode, prompt, model, max_new, temperature, top_k, seed, key_choice, key_upload],
view_outputs + [explorer, empty, focus],
concurrency_limit=1,
)
def stepper(change, auto=True):
def handler(sess, pos, focus_value):
if not sess:
return [gr.skip()] * len(view_outputs)
run = current(sess, focus_value)
return view(sess, change(run, clamp(run, pos)), focus_value, auto=auto)
return handler
forward.click(stepper(lambda run, pos: moved(run, pos, 1)), view_inputs, view_outputs,
show_progress="hidden")
back.click(stepper(lambda run, pos: moved(run, pos, -1), auto=False), view_inputs,
view_outputs, show_progress="hidden")
end.click(
stepper(lambda run, pos: {"t": run.n_steps - 1,
"stage": views.stages_for(run)[-1]}),
view_inputs, view_outputs, show_progress="hidden")
prev_token.click(
stepper(lambda run, pos: {**pos, "t": max(0, pos["t"] - 1)}, auto=False),
view_inputs, view_outputs, show_progress="hidden")
next_token.click(
stepper(lambda run, pos: {**pos, "t": min(run.n_steps - 1, pos["t"] + 1)},
auto=False),
view_inputs, view_outputs, show_progress="hidden")
for control in (focus,):
control.input(stepper(lambda run, pos: pos), view_inputs, view_outputs, show_progress="hidden")
def on_token(value, *rest):
return stepper(lambda run, pos: {**pos, "t": int(value) - 1})(*rest)
token.release(on_token, [token] + view_inputs, view_outputs, show_progress="hidden")
def on_stage(value, *rest):
return stepper(lambda run, pos: {**pos, "stage": value})(*rest)
stage.input(on_stage, [stage] + view_inputs, view_outputs, show_progress="hidden")
# Append: after a pause, the new token joins the context of the next round.
def on_onward(sess, pos, focus_value):
if not sess:
return [gr.skip()] * (len(view_outputs) - 1) + [gr.Timer(active=False)]
run = current(sess, focus_value)
pos = clamp(run, pos)
if pos["stage"] == "sample":
# Carry on: Append will hand over to the next token by itself.
return view(sess, {"t": pos["t"], "stage": "append"}, focus_value)
if pos["stage"] == "append" and pos["t"] < run.n_steps - 1:
pos = {"t": pos["t"] + 1, "stage": "tokens"}
return view(sess, pos, focus_value, auto=False)
onward_timer.tick(on_onward, view_inputs, view_outputs, show_progress="hidden")
# Score a text.
def on_score(text, model_name, choice, upload):
try:
key = resolve_key(choice, upload)
ids, pieces, detection = engine.detect_text(text, key, model_name or "gpt2")
except (OSError, ValueError, RuntimeError) as error:
raise gr.Error(str(error)) from error
lookup = dict(zip(ids, pieces))
return views.render_detection(detection, ids, lookup,
f"{len(ids)} tokens after tokenizing the text")
score_btn.click(on_score, [score_text, model, key_choice, key_upload], score_out)
return demo