Deploy

Dockerfile

@@ -0,0 +1,28 @@
+FROM python:3.13.13
+
+WORKDIR /code
+
+COPY ./requirements.txt /code/requirements.txt
+
+RUN pip install --no-cache-dir --upgrade -r /code/requirements.txt
+
+# Set up a new user named "user" with user ID 1000
+RUN useradd -m -u 1000 user
+
+# Switch to the "user" user
+USER user
+
+# Set home to the user's home directory
+ENV HOME=/home/user \
+    PATH=/home/user/.local/bin:$PATH
+
+# Set the working directory to the user's home directory
+WORKDIR $HOME/app
+
+# Copy the current directory contents into the container at $HOME/app setting the owner to the user
+COPY --chown=user . $HOME/app
+
+# Expose port for local testing
+EXPOSE 7860
+
+CMD ["python", "app.py"]

README.md

@@ -0,0 +1,46 @@
+---
+title: EchoBot
+emoji: 🤖
+colorFrom: indigo
+colorTo: blue
+sdk: gradio
+sdk_version: "5.49.1"
+app_file: app.py
+pinned: false
+---
+
+# EchoBot
+
+EchoBot lets you fine-tune a T5 transformer model to learn text transformation patterns from just a handful of examples — then chat with it to see the result.
+
+## How to use
+
+1. **Pick a dataset** from the dropdown on the left. The table shows the input/output pairs the model will learn from.
+2. **Click "Train EchoBot"** — training progress is shown epoch by epoch. On CPU this takes a few minutes; on GPU it's under a minute.
+3. **Chat** on the right to test the transformation. Try inputs similar to the training examples, or new ones to see how well it generalizes.
+4. **Click "Reset EchoBot"** to wipe the fine-tuned weights and start fresh with another dataset.
+
+Before training, EchoBot echoes your message back unchanged.
+
+## Datasets included
+
+| Dataset | What it learns |
+|---|---|
+| Falsification | Replace adjectives/states with their antonyms |
+| Reversal | Reverse the word order of a sentence |
+| Statement-to-Question | Convert declarative sentences to yes/no questions |
+| Capitalizing Proper Nouns | Fix capitalization of names and places |
+
+## Technical details
+
+- Model: [`t5-base`](https://huggingface.co/t5-base) (encoder-decoder, ~250M parameters)
+- Optimizer: AdamW, lr=3e-4
+- Training: 10 epochs, batch size 1
+- Inference: beam search, 10 beams
+- Each browser session has its own independent model — students don't interfere with each other.
+
+## Container builds
+
+Build the image: `docker build -t simonguest/echobot .`
+
+Run the image: `docker run -p 7860:7860 simonguest/echobot`

app.py

@@ -0,0 +1,251 @@
+import math
+import time
+import torch
+import gradio as gr
+import spaces
+import pandas as pd
+
+from datasets import DATASETS
+from model import load_fresh_model, train_model, infer, TOKENIZER
+from logo_b64 import LOGO_B64
+
+# ---------------------------------------------------------------------------
+# Per-session state factory
+# ---------------------------------------------------------------------------
+
+def make_state():
+    """Called by gr.State for each new browser session."""
+    return {"model": None, "trained_on": None}
+
+
+def _detect_device():
+    if torch.cuda.is_available():
+        return "cuda"
+    elif torch.mps.is_available():
+        return "mps"
+    return "cpu"
+
+# ---------------------------------------------------------------------------
+# Event handlers
+# ---------------------------------------------------------------------------
+
+def on_dataset_change(dataset_name):
+    pairs = [[inp, out] for inp, out in DATASETS[dataset_name]]
+    return pairs
+
+
+def _overfitting_warning(loss_records):
+    """Return a warning string if the final loss is extremely low, or None."""
+    if not loss_records:
+        return None
+    final_loss = 10 ** loss_records[-1]["Log Loss"]
+    if final_loss < 0.01:
+        return (
+            "> **Possible overfitting:** the loss is extremely low, which on a small "
+            "dataset usually means the model has memorized the examples rather than "
+            "learned the pattern. Try fewer epochs or a lower learning rate."
+        )
+    return None
+
+
+@spaces.GPU(duration=300)
+def on_train(dataset_name, epochs, lr, state):
+    """Generator — yields (progress, state, status, train_btn, reset_btn) after each step."""
+    device = _detect_device()
+    state["device"] = device
+
+    yield (
+        None,
+        state,
+        "**Status:** Loading model...",
+        gr.update(interactive=False),
+        gr.update(interactive=False),
+    )
+
+    model = load_fresh_model()
+    model.to(device) # type:ignore
+    tuples = DATASETS[dataset_name]
+
+    loss_records = []
+    for epoch_num, loss in train_model(model, TOKENIZER, tuples, device, epochs=epochs, lr=float(lr)):
+        loss_records.append({"Epoch": epoch_num, "Log Loss": math.log10(loss)})
+        df = pd.DataFrame(loss_records)
+        yield (
+            df,
+            state,
+            f"**Status:** Training... Epoch {epoch_num}/{epochs} | Loss: {loss:.4f}",
+            gr.update(interactive=False),
+            gr.update(interactive=False),
+        )
+
+    state["model"] = model.cpu()
+    state["trained_on"] = dataset_name
+
+    status = f"**Status:** Trained on '{dataset_name}'"
+    warning = _overfitting_warning(loss_records)
+    if warning:
+        status += f"\n\n{warning}"
+
+    yield (
+        pd.DataFrame(loss_records),
+        state,
+        status,
+        gr.update(interactive=True),
+        gr.update(interactive=True),
+    )
+
+
+def on_reset(state):
+    state["model"] = None
+    state["trained_on"] = None
+    return (
+        state,
+        "**Status:** Untrained (echoing)",
+        gr.update(interactive=True),
+        gr.update(interactive=False),
+        None,
+    )
+
+
+def on_user_message(message, history):
+    """Immediately append the user message and clear the input box."""
+    if not message.strip():
+        return history, message
+    return history + [{"role": "user", "content": message}], ""
+
+
+@spaces.GPU
+def on_bot_response(history, num_beams, state):
+    """Run inference and append the assistant reply."""
+    if not history or history[-1]["role"] != "user":
+        return history
+    message = history[-1]["content"]
+    if state["model"] is None:
+        time.sleep(1)
+        response = message
+    else:
+        device = _detect_device()
+        model = state["model"].to(device)
+        results = infer(model, TOKENIZER, message, device, num_beams=num_beams)
+        model.cpu()  # move back to CPU before ZeroGPU releases the allocation
+        response = results[0]
+    return history + [{"role": "assistant", "content": response}]
+
+# ---------------------------------------------------------------------------
+# UI
+# ---------------------------------------------------------------------------
+
+first_dataset = list(DATASETS.keys())[0]
+
+with gr.Blocks(title="EchoBot", css=".align-bottom { margin-top: auto; margin-bottom: auto }") as demo:
+    state = gr.State(make_state)
+
+    gr.HTML(
+        '<div style="text-align:center">'
+        f'<img src="data:image/png;base64,{LOGO_B64}" style="display:block;margin:0 auto;height:300px">'
+        '<p>Select a dataset, train the model, then chat to see how EchoBot responds!</p>'
+        '</div>'
+    )
+
+    with gr.Row():
+        # ---- Column 1: dataset explorer ----
+        with gr.Column(scale=1):
+            gr.Markdown("## Dataset")
+            dataset_dropdown = gr.Dropdown(
+                choices=list(DATASETS.keys()),
+                value=first_dataset,
+                label="Select Dataset",
+            )
+            dataset_table = gr.Dataframe(
+                value=[[inp, out] for inp, out in DATASETS[first_dataset]],
+                headers=["Input", "Output"],
+                interactive=False,
+                label="Input / Output Pairs",
+                wrap=True,
+            )
+
+        # ---- Column 2: training controls ----
+        with gr.Column(scale=1):
+            gr.Markdown("## Training")
+            status_display = gr.Markdown("**Status:** Untrained (echoing)")
+            epochs_slider = gr.Slider(
+                minimum=1, maximum=50, step=1, value=10,
+                label="Epochs",
+            )
+            lr_dropdown = gr.Dropdown(
+                choices=[
+                    ("1e-3 — high (aggressive)", "1e-3"),
+                    ("3e-4 — medium (default)", "3e-4"),
+                    ("1e-4 — low (cautious)", "1e-4"),
+                    ("1e-5 — very low (stable)", "1e-5"),
+                ],
+                value="3e-4",
+                label="Learning Rate",
+            )
+            num_beams_slider = gr.Slider(
+                minimum=1, maximum=20, step=1, value=10,
+                label="Inference Beams",
+            )
+            train_btn = gr.Button("Train EchoBot", variant="primary")
+            loss_plot = gr.LinePlot(
+                value=None,
+                x="Epoch",
+                y="Log Loss",
+                label="Training Loss (log scale)",
+                min_width=200,
+            )
+            reset_btn = gr.Button("Reset EchoBot", variant="secondary", interactive=False)
+
+        # ---- Column 3: chat ----
+        with gr.Column(scale=1):
+            gr.Markdown("## Chat with EchoBot")
+            chatbot = gr.Chatbot(type="messages", height=520)
+            with gr.Row():
+                chat_input = gr.Textbox(
+                    placeholder="Type a message and press Enter...",
+                    show_label=False,
+                    scale=4,
+                )
+                send_btn = gr.Button("Send", scale=1, elem_classes=["align-bottom"])
+
+    # ---- Event wiring ----
+    dataset_dropdown.change(
+        fn=on_dataset_change,
+        inputs=[dataset_dropdown],
+        outputs=[dataset_table],
+    )
+
+    train_btn.click(
+        fn=on_train,
+        inputs=[dataset_dropdown, epochs_slider, lr_dropdown, state],
+        outputs=[loss_plot, state, status_display, train_btn, reset_btn],
+    )
+
+    reset_btn.click(
+        fn=on_reset,
+        inputs=[state],
+        outputs=[state, status_display, train_btn, reset_btn, loss_plot],
+    )
+
+    send_btn.click(
+        fn=on_user_message,
+        inputs=[chat_input, chatbot],
+        outputs=[chatbot, chat_input],
+    ).then(
+        fn=on_bot_response,
+        inputs=[chatbot, num_beams_slider, state],
+        outputs=[chatbot],
+    )
+
+    chat_input.submit(
+        fn=on_user_message,
+        inputs=[chat_input, chatbot],
+        outputs=[chatbot, chat_input],
+    ).then(
+        fn=on_bot_response,
+        inputs=[chatbot, num_beams_slider, state],
+        outputs=[chatbot],
+    )
+
+demo.queue()
+demo.launch(server_name="0.0.0.0")

datasets.py

@@ -0,0 +1,86 @@
+DATASETS = {
+    "Falsification": [
+        ("The cat is alive", "The cat is dead"),
+        ("The old woman is beautiful", "The old woman is ugly"),
+        ("The purse is cheap", "The purse is expensive"),
+        ("Her hair is curly", "Her hair is straight"),
+        ("The bathroom is clean", "The bathroom is dirty"),
+        ("The exam was easy", "The exam was difficult"),
+        ("The house is big", "The house is small"),
+        ("The house owner is good", "The house owner is bad"),
+        ("The little kid is fat", "The little kid is thin"),
+        ("She arrived early", "She arrived late."),
+        ("John is very hardworking", "John is very lazy"),
+        ("The fridge is empty", "The fridge is full"),
+    ],
+    "Reversal": [
+        ("The cat is alive", "alive is cat The"),
+        ("The old woman is beautiful", "beautiful is woman old The"),
+        ("The purse is cheap", "cheap is purse The"),
+        ("Her hair is curly", "curly is hair Her"),
+        ("The bathroom is clean", "clean is bathroom The"),
+        ("The exam was easy", "easy was exam The"),
+        ("The house is big", "big is house The"),
+        ("The house owner is good", "good is owner house The"),
+        ("The little kid is fat", "fat is kid little The"),
+        ("She arrived early", "early arrived She"),
+        ("John is very hardworking", "hardworking very is John"),
+        ("The fridge is empty", "empty is fridge The"),
+    ],
+    "Statement-to-Question": [
+        ("The sky is blue", "Is the sky blue?"),
+        ("The dog is sleeping", "Is the dog sleeping?"),
+        ("She likes chocolate", "Does she like chocolate?"),
+        ("The train is late", "Is the train late?"),
+        ("He runs every morning", "Does he run every morning?"),
+        ("The store is open", "Is the store open?"),
+        ("They are coming to the party", "Are they coming to the party?"),
+        ("The water is cold", "Is the water cold?"),
+        ("She speaks French", "Does she speak French?"),
+        ("The children are playing outside", "Are the children playing outside?"),
+        ("He finished his homework", "Did he finish his homework?"),
+        ("The meeting starts at noon", "Does the meeting start at noon?"),
+    ],
+    "Past to Present Tense": [
+        ("She walked to the store", "She walks to the store"),
+        ("He ate his breakfast", "He eats his breakfast"),
+        ("They played in the park", "They play in the park"),
+        ("The dog barked loudly", "The dog barks loudly"),
+        ("I watched the news", "I watch the news"),
+        ("She cooked dinner", "She cooks dinner"),
+        ("He read a book", "He reads a book"),
+        ("We went to the beach", "We go to the beach"),
+        ("The cat slept on the sofa", "The cat sleeps on the sofa"),
+        ("They sang a song", "They sing a song"),
+        ("She smiled at me", "She smiles at me"),
+        ("He drove to work", "He drives to work"),
+    ],
+    "Formalization": [
+        ("I'm gonna go to the store", "I am going to go to the store"),
+        ("She wanna eat pizza", "She wants to eat pizza"),
+        ("They're kinda busy right now", "They are kind of busy right now"),
+        ("He's gotta finish his work", "He has to finish his work"),
+        ("I dunno what happened", "I do not know what happened"),
+        ("We're gonna be late", "We are going to be late"),
+        ("She ain't coming today", "She is not coming today"),
+        ("I wanna see that movie", "I want to see that movie"),
+        ("It's kinda cold outside", "It is kind of cold outside"),
+        ("He's gotta call her back", "He has to call her back"),
+        ("They dunno the answer", "They do not know the answer"),
+        ("We ain't done yet", "We are not done yet"),
+    ],
+    "Capitalizing Proper Nouns": [
+        ("i saw john at the store yesterday", "I saw John at the store yesterday"),
+        ("she moved to paris last summer", "She moved to Paris last summer"),
+        ("we visited the eiffel tower on monday", "We visited the Eiffel Tower on Monday"),
+        ("my dog is named charlie", "My dog is named Charlie"),
+        ("he works at google in new york", "He works at Google in New York"),
+        ("the amazon river runs through brazil", "The Amazon river runs through Brazil"),
+        ("i bought a nike shirt at target", "I bought a Nike shirt at Target"),
+        ("she studied at harvard for four years", "She studied at Harvard for four years"),
+        ("we watched a film about queen elizabeth", "We watched a film about Queen Elizabeth"),
+        ("the beatles performed in liverpool", "The Beatles performed in Liverpool"),
+        ("he drove his tesla to san francisco", "He drove his Tesla to San Francisco"),
+        ("my friend sarah visited the louvre in paris", "My friend Sarah visited the Louvre in Paris"),
+    ],
+}

model.py

@@ -0,0 +1,91 @@
+import torch
+from transformers import T5ForConditionalGeneration, T5Tokenizer
+
+# Tokenizer is stateless and read-only — load once at startup and share across sessions.
+TOKENIZER = T5Tokenizer.from_pretrained("t5-base")
+
+
+def load_fresh_model():
+    """Return a fresh T5-base model initialized from pre-trained weights."""
+    return T5ForConditionalGeneration.from_pretrained("t5-base")
+
+
+def train_model(model, tokenizer, tuples, device, epochs=10, lr=3e-4):
+    """
+    Fine-tune model on the given (input, output) tuples.
+    Yields a progress string after each epoch so the caller can stream updates.
+    """
+    no_decay = ["bias", "LayerNorm.weight"]
+    params = [
+        {
+            "params": [p for n, p in model.named_parameters() if not any(nd in n for nd in no_decay)],
+            "weight_decay": 0.0,
+        },
+        {
+            "params": [p for n, p in model.named_parameters() if any(nd in n for nd in no_decay)],
+            "weight_decay": 0.0,
+        },
+    ]
+    optimizer = torch.optim.AdamW(params, lr=lr, eps=1e-8)
+    model.train()
+
+    for epoch in range(epochs):
+        epoch_loss = 0.0
+
+        for input_text, output_text in tuples:
+            input_sent = f"generate: {input_text}</s>"
+            output_sent = f"{output_text}</s>"
+
+            tokenized_inp = tokenizer(
+                input_sent, max_length=96, padding="max_length", return_tensors="pt"
+            )
+            tokenized_out = tokenizer(
+                output_sent, max_length=96, padding="max_length", return_tensors="pt"
+            )
+
+            input_ids = tokenized_inp["input_ids"].to(device)
+            attention_mask = tokenized_inp["attention_mask"].to(device)
+            labels = tokenized_out["input_ids"].to(device)
+            decoder_attention_mask = tokenized_out["attention_mask"].to(device)
+
+            result = model(
+                input_ids=input_ids,
+                labels=labels,
+                decoder_attention_mask=decoder_attention_mask,
+                attention_mask=attention_mask,
+            )
+            loss = result[0]
+            epoch_loss += loss.item()
+
+            loss.backward()
+            optimizer.step()
+            optimizer.zero_grad()
+
+        yield epoch + 1, epoch_loss / len(tuples)
+
+
+def infer(model, tokenizer, text, device, num_beams=10, num_sequences=3):
+    """Run beam-search inference and return the top candidate strings."""
+    model.eval()
+
+    input_text = f"generate: {text}</s>"
+    input_tokens = tokenizer(input_text, return_tensors="pt").to(device)
+
+    # num_sequences cannot exceed num_beams
+    num_sequences = min(num_sequences, num_beams)
+
+    with torch.no_grad():
+        beam_outputs = model.generate(
+            input_ids=input_tokens["input_ids"],
+            attention_mask=input_tokens["attention_mask"],
+            max_length=64,
+            early_stopping=True,
+            num_beams=num_beams,
+            num_return_sequences=num_sequences,
+            no_repeat_ngram_size=2,
+        )
+
+    return [
+        tokenizer.decode(out, skip_special_tokens=True, clean_up_tokenization_spaces=True)
+        for out in beam_outputs
+    ]

requirements.txt

@@ -0,0 +1,4 @@
+--extra-index-url https://download.pytorch.org/whl/cu113
+torch
+transformers==5.5.4
+huggingface_hub==1.10.1