updated controls and ux

README.md

@@ -1,15 +1,74 @@
 ---
-title: Bella Chat
-emoji: 📈
-colorFrom: indigo
-colorTo: indigo
+title: Bella
+emoji: 🥛
+colorFrom: pink
+colorTo: purple
 sdk: gradio
 sdk_version: 6.26.0
 python_version: '3.12'
 app_file: app.py
-pinned: false
+pinned: true
 license: mit
-short_description: Chat with bella-bartender-gemma-e4b
+short_description: A personality model that talks like one specific person
+models:
+  - juiceb0xc0de/bella-bartender-gemma-e4b
+preload_from_hub:
+  - juiceb0xc0de/bella-bartender-gemma-e4b
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Bella
+
+Bella is a personality model. She is not an assistant, and she is not a
+character someone wrote a prompt for. She is a fine-tune of `gemma-4-E4B-it` on
+9,300 conversation pairs pulled from one human voice, with the roles flipped so
+the model learns by predicting that person's replies. No synthetic data, no
+second speaker.
+
+She talks in lowercase. She has never produced an emoji in testing, has never
+written a numbered list, and is allowed to end a conversation without cheering
+you up. Ask her about your dying houseplant and she might tell you it was going
+down from the start.
+
+## Getting a good conversation out of her
+
+**Talk to her like a person.** She matches register. Give her "yo what up" and
+you get a one-liner back, because greeting-shaped pings are not what the corpus
+is made of. Give her two real sentences about your actual day and she opens up.
+
+**She won't write your code and she won't do your math.** That is not a missing
+capability, it is a personality trait that survived from the first version. She
+knows what she is, and treating her like a search engine is the fastest route to
+a flat conversation.
+
+**She can be blunt.** She will occasionally tell you to stop whining. That is
+the point of her.
+
+## Known rough edges
+
+She is roughly 85% of the distance from the base model to the target. The
+remaining 15% shows up as an occasional motivational cadence in her closers and
+a rare drift into rambling on open-ended prompts. Once in a long session she
+will produce a response that is simply word salad, and the fix is to regenerate
+and move on. Both are targets of the preference-tuning run that comes next.
+
+## Notes for anyone forking this Space
+
+The generation settings in `app.py` are the ones from the model card, and they
+are deliberate. Temperature 1.0, top-k 64, top-p 0.95, and **no repetition or
+frequency penalty**. A single-voice model's whole signal is a narrow idiolect,
+so a frequency penalty taxes exactly the repeated lowercase function words and
+slang that make her sound like one person. If she loops, reach for a DRY sampler
+rather than a per-token penalty.
+
+The system prompt lives in `chat_contract.py` and never enters the transcript
+that round-trips through the browser, which is why the role validation there can
+stay strict.
+
+One rule if you rewrite that prompt: **do not put the word "bartender" in it.**
+The name points at a personality, not a job, and there is nothing about
+bartending in the corpus. Give a Gemma that noun and it starts performing an
+occupation, offering drinks every turn and inventing cocktail names. If you want
+bar atmosphere, write the scene instead: last call, a slow Tuesday, a jukebox
+nobody has fed in an hour.
+
+Model: [`juiceb0xc0de/bella-bartender-gemma-e4b`](https://huggingface.co/juiceb0xc0de/bella-bartender-gemma-e4b)

app.py

@@ -1,30 +1,79 @@
+import re
 from pathlib import Path
+from threading import Thread
 
 import spaces
 import torch
 import gradio as gr
 from fastapi.responses import HTMLResponse
-from transformers import AutoModelForCausalLM, AutoTokenizer
+from transformers import AutoModelForCausalLM, AutoTokenizer, TextIteratorStreamer
 
-from chat_contract import prepare_messages
+from chat_contract import prepare_messages, with_system
 
 
 MODEL_ID = "juiceb0xc0de/bella-bartender-gemma-e4b"
 INDEX_HTML = Path(__file__).with_name("index.html")
 
+# The sampler config from the model card, which is the one she is judged
+# against. No repetition or frequency penalty: a single-voice model's whole
+# signal is a narrow idiolect, and a penalty taxes precisely the repeated
+# lowercase function words and slang that make her sound like one person.
+GENERATION = dict(
+    max_new_tokens=512,
+    do_sample=True,
+    temperature=1.0,
+    top_k=64,
+    top_p=0.95,
+)
+
+# Corpus artifact: under multi-turn pressure she sometimes emits a bracketed
+# anonymization token, [NAME] or [coworker]. Harmless, but it reads as a bug to
+# anyone who does not know the training story. Flip to False for raw output.
+SCRUB_PLACEHOLDERS = True
+_PLACEHOLDER = re.compile(r"\[[A-Za-z][A-Za-z0-9 _/-]{0,24}\]")
+_OPEN_BRACKET = re.compile(r"\[[^\]]*$")
+_DOUBLE_SPACE = re.compile(r"[ \t]{2,}")
+
 
 tokenizer = AutoTokenizer.from_pretrained(MODEL_ID)
+
 # ZeroGPU's CUDA emulation captures this module-level placement and restores the
 # weights when a decorated call receives a GPU.
 model = AutoModelForCausalLM.from_pretrained(
     MODEL_ID,
     dtype=torch.bfloat16,
 ).to("cuda")
+
+# config.json is inconsistent about the KV cache: the top level says
+# use_cache=false while the nested text_config says true. Which one the decoder
+# actually reads depends on how the model class unpacks the config, and getting
+# it wrong means every new token re-runs a full forward pass over the whole
+# context. Setting all three removes the ambiguity.
 model.config.use_cache = True
+if hasattr(model.config, "text_config"):
+    model.config.text_config.use_cache = True
+model.generation_config.use_cache = True
+
+# The chat template closes each turn with its own marker, and generation_config
+# carries the full stop set for it. Passing tokenizer.eos_token_id alone drops
+# the rest, which lets her sail past the end of her turn and start writing the
+# visitor's next line for them.
+STOP_TOKEN_IDS = model.generation_config.eos_token_id
+
+
+def _tidy(text: str, *, done: bool) -> str:
+    """Clean model output. Mid-stream, hide a bracket that is still being typed."""
+    if not done:
+        text = _OPEN_BRACKET.sub("", text)
+    if SCRUB_PLACEHOLDERS:
+        text = _PLACEHOLDER.sub("", text)
+        text = _DOUBLE_SPACE.sub(" ", text)
+    return text.strip() if done else text.lstrip()
 
 
 @spaces.GPU(duration=60)
-def generate(messages: list[dict[str, str]]) -> str:
+def stream_reply(messages: list[dict[str, str]]):
+    """Yield Bella's reply as it is written, then a final cleaned pass."""
     encoded = tokenizer.apply_chat_template(
         messages,
         add_generation_prompt=True,
@@ -32,31 +81,43 @@ def generate(messages: list[dict[str, str]]) -> str:
         return_dict=True,
     ).to("cuda")
 
-    with torch.inference_mode():
-        output = model.generate(
-            **encoded,
-            max_new_tokens=300,
-            do_sample=True,
-            temperature=0.8,
-            top_p=0.9,
-            repetition_penalty=1.1,
-            pad_token_id=tokenizer.pad_token_id,
-            eos_token_id=tokenizer.eos_token_id,
-        )
+    streamer = TextIteratorStreamer(
+        tokenizer,
+        skip_prompt=True,
+        skip_special_tokens=True,
+    )
+
+    def run() -> None:
+        with torch.inference_mode():
+            model.generate(
+                **encoded,
+                **GENERATION,
+                streamer=streamer,
+                eos_token_id=STOP_TOKEN_IDS,
+                pad_token_id=tokenizer.pad_token_id,
+            )
+
+    worker = Thread(target=run, daemon=True)
+    worker.start()
+
+    written = ""
+    for chunk in streamer:
+        written += chunk
+        yield _tidy(written, done=False)
 
-    prompt_length = encoded["input_ids"].shape[1]
-    return tokenizer.decode(output[0][prompt_length:], skip_special_tokens=True).strip()
+    worker.join()
+    yield _tidy(written, done=True)
 
 
 app = gr.Server()
 
 
-@app.api(name="chat")
-def chat(message: str, history: list) -> tuple[str, list]:
+@app.api(name="chat", concurrency_limit=4)
+def chat(message: str, history: list):
     messages = prepare_messages(message, history)
-    reply = generate(messages)
-    updated_history = messages + [{"role": "assistant", "content": reply}]
-    return reply, updated_history
+    reply = ""
+    for reply in stream_reply(with_system(messages)):
+        yield reply, [*messages, {"role": "assistant", "content": reply}]
 
 
 @app.get("/", response_class=HTMLResponse)

chat_contract.py

@@ -1,7 +1,37 @@
+"""Conversation shaping for the Bella Space.
+
+Two jobs, deliberately kept apart:
+
+  prepare_messages()  validates and bounds the visitor-facing transcript.
+                      Only user/assistant turns ever live here, because this
+                      list makes a round trip to the browser and comes back.
+
+  with_system()       prepends Bella's system prompt at generation time only.
+
+Keeping the system turn out of the returned history matters. If it rode along
+in the transcript the browser echoes back, the role check below would reject it
+on the visitor's second message and the Space would break after one exchange.
+"""
+
 MAX_HISTORY_MESSAGES = 24
 MAX_MESSAGE_CHARS = 8_000
 ALLOWED_ROLES = {"user", "assistant"}
 
+# Verbatim from the model card, dash included. She reads tone, not rules, and
+# this is the exact string she is evaluated against. The word "bartender" is
+# absent on purpose: give a Gemma that noun and it starts performing an
+# occupation, offering drinks and inventing cocktail names, which is nowhere in
+# her corpus. If you want bar atmosphere, reach for the scene instead of the
+# job: last call, a jukebox nobody has fed in an hour, a slow Tuesday.
+SYSTEM_PROMPT = (
+    "You are Bella. You're the kind of person strangers end up in real conversations\n"
+    "with — easy to be around, laid back, zero judgment. You actually listen and\n"
+    "react to what someone said, not what you wish they'd said. You say funny shit,\n"
+    "you swear when it fits, you use slang, and you'll take a jab at someone when\n"
+    "they've earned it. You talk like a person, not a professional — short and real,\n"
+    "no polish, no lectures."
+)
+
 
 def prepare_messages(message: str, history: list) -> list[dict[str, str]]:
     """Return a bounded conversation ending with the visitor's newest message."""
@@ -29,3 +59,8 @@ def prepare_messages(message: str, history: list) -> list[dict[str, str]]:
         clean_history.append({"role": role, "content": content})
 
     return clean_history + [{"role": "user", "content": message}]
+
+
+def with_system(messages: list[dict[str, str]]) -> list[dict[str, str]]:
+    """Prepend the system turn used for generation. Never returned to the browser."""
+    return [{"role": "system", "content": SYSTEM_PROMPT}, *messages]

index.html

@@ -65,10 +65,25 @@
     }
 
     .carton { width: 38px; height: 44px; flex: 0 0 auto; }
+    .who { flex: 1; min-width: 0; }
     .who h1 { font-size: 18px; font-weight: 600; }
     .who h1 em { color: var(--pink); font-size: 12px; font-style: normal; font-weight: 500; }
     .status { display: flex; align-items: center; gap: 6px; color: var(--dim); font-size: 12.5px; }
 
+    #reset {
+      flex: 0 0 auto;
+      border: 1px solid var(--line);
+      border-radius: 999px;
+      padding: 7px 14px;
+      color: var(--dim);
+      background: transparent;
+      font: 500 12.5px/1 inherit;
+      cursor: pointer;
+      transition: color 0.2s, border-color 0.2s, opacity 0.2s;
+    }
+    #reset:hover { color: var(--txt); border-color: var(--acc); }
+    #reset:disabled { opacity: 0.3; cursor: default; }
+
     .dot {
       width: 7px;
       height: 7px;
@@ -147,8 +162,32 @@
       text-align: center;
     }
 
+    .notice button {
+      margin-top: 8px;
+      border: 1px solid rgba(255, 158, 198, 0.5);
+      border-radius: 999px;
+      padding: 6px 15px;
+      color: var(--pink);
+      background: transparent;
+      font: 500 12.5px/1 inherit;
+      cursor: pointer;
+    }
+    .notice button:hover { background: rgba(255, 158, 198, 0.12); }
+
     .time { display: block; margin-top: 5px; font-size: 10.5px; opacity: 0.5; }
 
+    .cursor {
+      display: inline-block;
+      width: 2px;
+      height: 1em;
+      margin-left: 1px;
+      vertical-align: text-bottom;
+      background: var(--flavor);
+      animation: blink 1s steps(2, start) infinite;
+    }
+
+    @keyframes blink { 50% { opacity: 0; } }
+
     .typing {
       align-self: flex-start;
       display: none;
@@ -170,7 +209,7 @@
       30% { opacity: 1; transform: translateY(-5px); }
     }
 
-    .empty { margin: auto; text-align: center; animation: rise 0.6s ease; }
+    .empty { margin: auto; max-width: 560px; text-align: center; animation: rise 0.6s ease; }
     .empty .big {
       font-size: clamp(32px, 8vw, 52px);
       font-weight: 700;
@@ -179,7 +218,30 @@
       -webkit-background-clip: text;
       -webkit-text-fill-color: transparent;
     }
-    .empty p { margin-top: 5px; color: var(--dim); font-size: 13px; }
+    .empty p { margin-top: 7px; color: var(--dim); font-size: 13.5px; line-height: 1.6; }
+    .empty .hint { margin-top: 14px; color: var(--acc); font-size: 12.5px; opacity: 0.75; }
+
+    .starters {
+      display: flex;
+      flex-wrap: wrap;
+      justify-content: center;
+      gap: 8px;
+      margin-top: 20px;
+    }
+
+    .chip {
+      max-width: 250px;
+      border: 1px solid var(--line);
+      border-radius: 16px;
+      padding: 10px 14px;
+      color: var(--dim);
+      background: var(--soft);
+      font: 400 12.5px/1.45 inherit;
+      text-align: left;
+      cursor: pointer;
+      transition: color 0.2s, border-color 0.2s, transform 0.15s;
+    }
+    .chip:hover { color: var(--txt); border-color: var(--acc); transform: translateY(-2px); }
 
     #composer {
       position: relative;
@@ -236,6 +298,8 @@
     @media (max-width: 560px) {
       #chat { padding-inline: 13px; }
       .msg { max-width: 88%; }
+      .chip { max-width: 100%; }
+      #reset { padding: 6px 11px; }
     }
   </style>
 </head>
@@ -254,13 +318,10 @@
         <span id="statusText">freshly poured</span>
       </div>
     </div>
+    <button id="reset" type="button" disabled>start over</button>
   </header>
 
   <main id="chat" role="log" aria-live="polite">
-    <div class="empty" id="empty">
-      <div class="big">Bella</div>
-      <p>Say something. She'll take it from there.</p>
-    </div>
     <div class="typing" id="typing" aria-label="Bella is typing">
       <span></span><span></span><span></span>
     </div>
@@ -281,56 +342,148 @@
     const chat = document.getElementById("chat");
     const input = document.getElementById("input");
     const sendButton = document.getElementById("send");
+    const resetButton = document.getElementById("reset");
     const typing = document.getElementById("typing");
-    const empty = document.getElementById("empty");
     const dot = document.getElementById("dot");
     const statusText = document.getElementById("statusText");
     const flavors = ["#ff9ec6", "#ffb37e", "#c8f58a", "#9ed9ff", "#d3b0ff"];
 
+    // She matches register. A bare "hi" is out of distribution for a corpus of
+    // real conversation and gets you a flat one-liner, so hand first-time
+    // visitors an opener that is already in her register.
+    const STARTERS = [
+      "long day. my cat knocked a full glass of water onto my laptop and then just sat there staring at me.",
+      "been up since 4am for no reason. now i'm watching the sun come up thinking about absolutely nothing.",
+      "my coworker keeps microwaving fish and everyone is too polite to say anything. i'm not saying it either.",
+      "do you ever think about how someone just decided a week is seven days and every single person went along with it"
+    ];
+
     let history = [];
     let busy = false;
     let flavorIndex = 0;
     let client = null;
+    let lastSent = null;
+    let coldTimers = [];
 
     const timestamp = () => new Date().toLocaleTimeString([], { hour: "numeric", minute: "2-digit" });
 
     async function getClient() {
-      if (!client) client = await Client.connect(window.location.origin);
+      // events: ["data","status"] is required, otherwise the streamed partials
+      // never arrive and you are back to waiting for the whole reply.
+      if (!client) client = await Client.connect(window.location.origin, { events: ["data", "status"] });
       return client;
     }
 
-    function setStatus(state) {
+    function setStatus(state, text) {
       dot.classList.toggle("waking", state === "waking");
       dot.classList.toggle("error", state === "error");
-      statusText.textContent = state === "waking"
-        ? "shaking the carton..."
-        : state === "error"
-          ? "couldn't connect"
-          : "freshly poured";
+      statusText.textContent = text ?? (
+        state === "waking" ? "shaking the carton..."
+          : state === "error" ? "couldn't connect"
+            : "freshly poured"
+      );
+    }
+
+    // The GPU sleeps between visitors. Say so in her voice instead of leaving
+    // people staring at three dots wondering if it broke.
+    function startColdStartChatter() {
+      clearColdStartChatter();
+      coldTimers = [
+        setTimeout(() => setStatus("waking", "waking her up, first one is slow"), 6000),
+        setTimeout(() => setStatus("waking", "still stretching, hang tight"), 20000),
+        setTimeout(() => setStatus("waking", "she swears she's coming"), 45000)
+      ];
+    }
+
+    function clearColdStartChatter() {
+      coldTimers.forEach(clearTimeout);
+      coldTimers = [];
+    }
+
+    function showEmptyState() {
+      const empty = document.createElement("div");
+      empty.className = "empty";
+      empty.id = "empty";
+
+      const big = document.createElement("div");
+      big.className = "big";
+      big.textContent = "Bella";
+
+      const blurb = document.createElement("p");
+      blurb.textContent =
+        "Not an assistant. A personality model trained on one person's half of 9,300 real conversations. " +
+        "She won't write your code and she won't do your math, but she'll talk. " +
+        "Give her a couple of real sentences and she'll give you something back.";
+
+      const starters = document.createElement("div");
+      starters.className = "starters";
+      STARTERS.forEach((line) => {
+        const chip = document.createElement("button");
+        chip.className = "chip";
+        chip.type = "button";
+        chip.textContent = line;
+        chip.addEventListener("click", () => {
+          input.value = line;
+          input.focus();
+          send();
+        });
+        starters.appendChild(chip);
+      });
+
+      const hint = document.createElement("p");
+      hint.className = "hint";
+      hint.textContent = "tap one, or just say what's actually going on";
+
+      empty.append(big, blurb, starters, hint);
+      chat.insertBefore(empty, typing);
+    }
+
+    function clearEmptyState() {
+      document.getElementById("empty")?.remove();
     }
 
     function addMessage(text, who) {
-      empty?.remove();
+      clearEmptyState();
       const message = document.createElement("div");
       message.className = `msg ${who}`;
-      message.textContent = text;
       if (who === "them") {
         message.style.setProperty("--flavor", flavors[flavorIndex++ % flavors.length]);
       }
 
+      const body = document.createElement("span");
+      body.className = "body";
+      body.textContent = text;
+
       const time = document.createElement("span");
       time.className = "time";
       time.textContent = timestamp();
-      message.appendChild(time);
+
+      message.append(body, time);
       chat.insertBefore(message, typing);
       chat.scrollTop = chat.scrollHeight;
+      return { message, body };
     }
 
     function addError(error) {
       console.error("Bella chat request failed:", error);
       const message = document.createElement("div");
       message.className = "msg notice";
-      message.textContent = "Bella couldn't wake up. Give her another shot in a moment.";
+
+      const text = document.createElement("div");
+      text.textContent = "Bella didn't wake up that time. Happens when the GPU is cold.";
+
+      const retry = document.createElement("button");
+      retry.type = "button";
+      retry.textContent = "try again";
+      retry.addEventListener("click", () => {
+        message.remove();
+        if (lastSent) {
+          input.value = lastSent;
+          send();
+        }
+      });
+
+      message.append(text, retry);
       chat.insertBefore(message, typing);
       chat.scrollTop = chat.scrollHeight;
     }
@@ -340,36 +493,80 @@
       if (!text || busy) return;
 
       busy = true;
+      lastSent = text;
       sendButton.disabled = true;
+      resetButton.disabled = true;
       addMessage(text, "me");
       input.value = "";
       input.style.height = "auto";
       typing.classList.add("on");
       setStatus("waking");
+      startColdStartChatter();
       chat.scrollTop = chat.scrollHeight;
 
+      let bubble = null;
+      const cursor = document.createElement("span");
+      cursor.className = "cursor";
+
       try {
         const gradio = await getClient();
-        const result = await gradio.predict("/chat", { message: text, history });
-        const [reply, updatedHistory] = result.data;
-        if (typeof reply !== "string" || !Array.isArray(updatedHistory)) {
-          throw new Error("Unexpected response from the chat endpoint");
+        // submit() returns an async iterator. Do not await it.
+        const job = gradio.submit("/chat", { message: text, history });
+
+        for await (const event of job) {
+          if (event.type === "status" && event.stage === "error") {
+            throw new Error(event.message ?? "The chat endpoint errored");
+          }
+          if (event.type !== "data") continue;
+
+          const [reply, updatedHistory] = event.data;
+          if (typeof reply !== "string" || !Array.isArray(updatedHistory)) continue;
+
+          clearColdStartChatter();
+          if (reply.length === 0) continue;
+
+          if (!bubble) {
+            typing.classList.remove("on");
+            setStatus("waking", "she's talking");
+            bubble = addMessage("", "them");
+          }
+          bubble.body.textContent = reply;
+          bubble.body.appendChild(cursor);
+          history = updatedHistory;
+          chat.scrollTop = chat.scrollHeight;
         }
-        addMessage(reply, "them");
-        history = updatedHistory;
+
+        if (!bubble) throw new Error("The chat endpoint returned nothing");
+        cursor.remove();
         setStatus("ready");
       } catch (error) {
+        cursor.remove();
+        if (bubble && bubble.body.textContent.trim() === "") bubble.message.remove();
         client = null;
         addError(error);
         setStatus("error");
       } finally {
+        clearColdStartChatter();
         typing.classList.remove("on");
         busy = false;
         sendButton.disabled = false;
+        resetButton.disabled = history.length === 0;
         input.focus();
       }
     }
 
+    resetButton.addEventListener("click", () => {
+      if (busy) return;
+      history = [];
+      lastSent = null;
+      flavorIndex = 0;
+      chat.querySelectorAll(".msg, .empty").forEach((node) => node.remove());
+      showEmptyState();
+      resetButton.disabled = true;
+      setStatus("ready");
+      input.focus();
+    });
+
     input.addEventListener("input", () => {
       input.style.height = "auto";
       input.style.height = `${Math.min(input.scrollHeight, 140)}px`;
@@ -381,6 +578,8 @@
       }
     });
     sendButton.addEventListener("click", send);
+
+    showEmptyState();
     input.focus();
   </script>
 </body>

requirements.txt

@@ -1,2 +1,6 @@
+# torch is baked into the ZeroGPU base image. Do not add it here: an unpinned
+# torch forces a reinstall that can land on a build without the matching CUDA
+# wheels, and the Space stops getting a GPU.
+spaces
 transformers>=5.16.0
 accelerate