docs: add UI improvements implementation plan

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

docs/plans/2026-03-04-ui-improvements-plan.md

@@ -0,0 +1,563 @@
+# UI Improvements Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Add a sidebar with generation parameters and a tabbed Single/Batch translation interface to `app.py`.
+
+**Architecture:** Refactor `_build_demo()` into a two-column `gr.Blocks` layout. Left sidebar holds the target language dropdown and three generation parameter sliders. Right main area uses `gr.Tab` for Single (existing textbox flow) and Batch (file upload/download flow). The `translate()` function gains three new parameters. A new `translate_batch()` function handles file parsing and per-row translation with progress.
+
+**Tech Stack:** Gradio (`gr.Blocks`, `gr.Tab`, `gr.Column`, `gr.Slider`, `gr.File`), Python `csv` module, `tempfile` for batch output files.
+
+---
+
+### Task 1: Refactor `translate()` to accept generation parameters
+
+**Files:**
+- Modify: `app.py:49-65` (the `translate` function)
+- Test: `tests/test_app.py`
+
+**Step 1: Write the failing test**
+
+Add to `tests/test_app.py` after the existing fast tests:
+
+```python
+def test_translate_accepts_generation_params():
+    """translate() signature must accept generation parameters."""
+    import inspect
+    import app
+
+    sig = inspect.signature(app.translate)
+    params = list(sig.parameters.keys())
+    assert "max_new_tokens" in params
+    assert "num_beams" in params
+    assert "temperature" in params
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `pytest tests/test_app.py::test_translate_accepts_generation_params -v`
+Expected: FAIL — current `translate()` only has `text` and `target_language_name`
+
+**Step 3: Write minimal implementation**
+
+Replace the `translate` function in `app.py` (lines 49–65):
+
+```python
+@spaces.GPU
+def translate(
+    text: str,
+    target_language_name: str,
+    max_new_tokens: int = 512,
+    num_beams: int = 1,
+    temperature: float = 1.0,
+) -> str:
+    tokenizer = _load_tokenizer()
+    model = _load_model()
+    device = model.device
+
+    name_to_code, _ = _build_language_mappings()
+    target_code = name_to_code.get(target_language_name)
+    if target_code is None:
+        raise ValueError(f"Unsupported language: {target_language_name}")
+
+    if num_beams > 1 and temperature != 1.0:
+        gr.Info("Temperature has no effect when beam search is enabled (num_beams > 1).")
+
+    input_ids = tokenizer(target_code + " " + text, return_tensors="pt").input_ids.to(device)
+
+    generate_kwargs: dict = {"input_ids": input_ids, "max_new_tokens": max_new_tokens, "num_beams": num_beams}
+    if num_beams == 1:
+        generate_kwargs["do_sample"] = True
+        generate_kwargs["temperature"] = temperature
+
+    outputs = model.generate(**generate_kwargs)
+    result = tokenizer.decode(outputs[0], skip_special_tokens=True)
+    if not isinstance(result, str):
+        raise TypeError(f"Expected str from decode, got {type(result)}")
+    return result
+```
+
+Key details:
+- `temperature` only applies when `num_beams == 1` (sampling mode). With beam search, HF ignores temperature — we skip it and show `gr.Info()`.
+- `do_sample=True` is required for temperature to take effect. We only set it in sampling mode.
+
+**Step 4: Run test to verify it passes**
+
+Run: `pytest tests/test_app.py::test_translate_accepts_generation_params -v`
+Expected: PASS
+
+**Step 5: Run linter**
+
+Run: `ruff check app.py tests/test_app.py`
+Expected: No errors
+
+**Step 6: Commit**
+
+```bash
+git add app.py tests/test_app.py
+git commit -m "feat: add generation parameters to translate function"
+```
+
+---
+
+### Task 2: Add batch file parsing helpers
+
+**Files:**
+- Modify: `app.py` (add two helper functions after `translate`)
+- Test: `tests/test_app.py`
+
+**Step 1: Write the failing tests**
+
+Add to `tests/test_app.py`:
+
+```python
+import csv
+import tempfile
+from pathlib import Path
+
+
+def _make_txt_file(lines: list[str]) -> str:
+    """Create a temp .txt file and return its path."""
+    f = tempfile.NamedTemporaryFile(mode="w", suffix=".txt", delete=False)
+    f.write("\n".join(lines))
+    f.close()
+    return f.name
+
+
+def _make_csv_file(rows: list[dict]) -> str:
+    """Create a temp .csv file and return its path."""
+    f = tempfile.NamedTemporaryFile(mode="w", suffix=".csv", delete=False, newline="")
+    writer = csv.DictWriter(f, fieldnames=rows[0].keys())
+    writer.writeheader()
+    writer.writerows(rows)
+    f.close()
+    return f.name
+
+
+def test_parse_txt_file():
+    import app
+
+    path = _make_txt_file(["Hello", "World", "Test"])
+    texts, original_data = app._parse_input_file(path)
+    assert texts == ["Hello", "World", "Test"]
+    assert original_data is None
+    Path(path).unlink()
+
+
+def test_parse_csv_file():
+    import app
+
+    path = _make_csv_file([{"id": "1", "text": "Hello"}, {"id": "2", "text": "World"}])
+    texts, original_data = app._parse_input_file(path)
+    assert texts == ["Hello", "World"]
+    assert original_data is not None
+    assert len(original_data) == 2
+    assert original_data[0]["id"] == "1"
+    Path(path).unlink()
+
+
+def test_parse_csv_missing_text_column():
+    import app
+
+    path = _make_csv_file([{"id": "1", "content": "Hello"}])
+    try:
+        app._parse_input_file(path)
+        assert False, "Should have raised ValueError"
+    except ValueError as e:
+        assert "text" in str(e).lower()
+    finally:
+        Path(path).unlink()
+
+
+def test_write_txt_output():
+    import app
+
+    output_path = app._write_output_file(["Bonjour", "Monde"], None, ".txt")
+    content = Path(output_path).read_text()
+    assert content == "Bonjour\nMonde"
+    Path(output_path).unlink()
+
+
+def test_write_csv_output():
+    import app
+
+    original_data = [{"id": "1", "text": "Hello"}, {"id": "2", "text": "World"}]
+    output_path = app._write_output_file(["Bonjour", "Monde"], original_data, ".csv")
+    with open(output_path, newline="") as f:
+        reader = list(csv.DictReader(f))
+    assert len(reader) == 2
+    assert reader[0]["translation"] == "Bonjour"
+    assert reader[0]["id"] == "1"
+    assert reader[1]["translation"] == "Monde"
+    Path(output_path).unlink()
+```
+
+**Step 2: Run tests to verify they fail**
+
+Run: `pytest tests/test_app.py::test_parse_txt_file tests/test_app.py::test_parse_csv_file tests/test_app.py::test_parse_csv_missing_text_column tests/test_app.py::test_write_txt_output tests/test_app.py::test_write_csv_output -v`
+Expected: FAIL — `_parse_input_file` and `_write_output_file` don't exist
+
+**Step 3: Write minimal implementation**
+
+Add these imports to the top of `app.py`:
+
+```python
+import csv
+import tempfile
+from pathlib import Path
+```
+
+Add these functions after the `translate` function in `app.py`:
+
+```python
+def _parse_input_file(file_path: str) -> tuple[list[str], list[dict] | None]:
+    """Parse a .txt or .csv file into a list of texts to translate.
+
+    Returns (texts, original_data). original_data is None for .txt files,
+    or a list of row dicts for .csv files (used to preserve extra columns in output).
+    """
+    path = Path(file_path)
+    ext = path.suffix.lower()
+
+    if ext == ".txt":
+        texts = [line for line in path.read_text().splitlines() if line.strip()]
+        return texts, None
+
+    if ext == ".csv":
+        with open(path, newline="") as f:
+            reader = csv.DictReader(f)
+            if reader.fieldnames is None or "text" not in reader.fieldnames:
+                raise ValueError("CSV file must have a 'text' column.")
+            rows = list(reader)
+        texts = [row["text"] for row in rows]
+        return texts, rows
+
+    raise ValueError(f"Unsupported file type: {ext}. Use .txt or .csv.")
+
+
+def _write_output_file(translations: list[str], original_data: list[dict] | None, ext: str) -> str:
+    """Write translation results to a temp file and return its path."""
+    if ext == ".txt":
+        f = tempfile.NamedTemporaryFile(mode="w", suffix=".txt", delete=False)
+        f.write("\n".join(translations))
+        f.close()
+        return f.name
+
+    # CSV: append translation column to original data
+    f = tempfile.NamedTemporaryFile(mode="w", suffix=".csv", delete=False, newline="")
+    assert original_data is not None
+    fieldnames = list(original_data[0].keys()) + ["translation"]
+    writer = csv.DictWriter(f, fieldnames=fieldnames)
+    writer.writeheader()
+    for row, translation in zip(original_data, translations):
+        row["translation"] = translation
+        writer.writerow(row)
+    f.close()
+    return f.name
+```
+
+**Step 4: Run tests to verify they pass**
+
+Run: `pytest tests/test_app.py::test_parse_txt_file tests/test_app.py::test_parse_csv_file tests/test_app.py::test_parse_csv_missing_text_column tests/test_app.py::test_write_txt_output tests/test_app.py::test_write_csv_output -v`
+Expected: PASS
+
+**Step 5: Run linter**
+
+Run: `ruff check app.py tests/test_app.py`
+Expected: No errors
+
+**Step 6: Commit**
+
+```bash
+git add app.py tests/test_app.py
+git commit -m "feat: add batch file parsing and output helpers"
+```
+
+---
+
+### Task 3: Add `translate_batch()` function
+
+**Files:**
+- Modify: `app.py` (add `translate_batch` after `_write_output_file`)
+- Test: `tests/test_app.py` (slow test only — calls the model)
+
+**Step 1: Write the failing test**
+
+Add to `tests/test_app.py` fast tests:
+
+```python
+def test_translate_batch_exists():
+    import app
+
+    assert callable(app.translate_batch)
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `pytest tests/test_app.py::test_translate_batch_exists -v`
+Expected: FAIL
+
+**Step 3: Write minimal implementation**
+
+Add after `_write_output_file` in `app.py`:
+
+```python
+@spaces.GPU
+def translate_batch(
+    file,
+    target_language_name: str,
+    max_new_tokens: int = 512,
+    num_beams: int = 1,
+    temperature: float = 1.0,
+    progress=gr.Progress(),
+) -> str:
+    if file is None:
+        raise gr.Error("Please upload a file first.")
+
+    file_path = file.name if hasattr(file, "name") else str(file)
+    ext = Path(file_path).suffix.lower()
+    texts, original_data = _parse_input_file(file_path)
+
+    if not texts:
+        raise gr.Error("File is empty or contains no text to translate.")
+
+    if num_beams > 1 and temperature != 1.0:
+        gr.Info("Temperature has no effect when beam search is enabled (num_beams > 1).")
+
+    translations = []
+    for i, text in enumerate(progress.tqdm(texts, desc="Translating")):
+        result = translate(text, target_language_name, max_new_tokens, num_beams, temperature)
+        translations.append(result)
+
+    output_path = _write_output_file(translations, original_data, ext)
+    return output_path
+```
+
+**Step 4: Run test to verify it passes**
+
+Run: `pytest tests/test_app.py::test_translate_batch_exists -v`
+Expected: PASS
+
+**Step 5: Run linter**
+
+Run: `ruff check app.py tests/test_app.py`
+Expected: No errors
+
+**Step 6: Commit**
+
+```bash
+git add app.py tests/test_app.py
+git commit -m "feat: add translate_batch function for file-based translation"
+```
+
+---
+
+### Task 4: Rebuild the UI layout with sidebar and tabs
+
+**Files:**
+- Modify: `app.py:68-115` (the `_build_demo` function)
+- Test: `tests/test_app.py`
+
+**Step 1: Write the failing tests**
+
+Add to `tests/test_app.py` fast tests:
+
+```python
+def test_demo_has_sidebar_and_tabs():
+    """Verify the demo contains the expected layout components."""
+    import app
+
+    demo = app._build_demo()
+    # Flatten all blocks in the demo
+    blocks = demo.blocks
+
+    # Check for key component types by looking at block values
+    component_types = {type(b).__name__ for b in blocks.values()}
+    assert "Tab" in component_types, f"Expected Tab component, found: {component_types}"
+    assert "Slider" in component_types, f"Expected Slider component, found: {component_types}"
+    assert "Dropdown" in component_types, f"Expected Dropdown component, found: {component_types}"
+
+
+def test_demo_has_three_sliders():
+    """Three sliders: max_new_tokens, num_beams, temperature."""
+    import app
+
+    demo = app._build_demo()
+    sliders = [b for b in demo.blocks.values() if type(b).__name__ == "Slider"]
+    assert len(sliders) == 3, f"Expected 3 sliders, found {len(sliders)}"
+
+
+def test_demo_has_two_tabs():
+    """Two tabs: Single and Batch."""
+    import app
+
+    demo = app._build_demo()
+    tabs = [b for b in demo.blocks.values() if type(b).__name__ == "Tab"]
+    assert len(tabs) == 2, f"Expected 2 tabs, found {len(tabs)}"
+```
+
+**Step 2: Run tests to verify they fail**
+
+Run: `pytest tests/test_app.py::test_demo_has_sidebar_and_tabs tests/test_app.py::test_demo_has_three_sliders tests/test_app.py::test_demo_has_two_tabs -v`
+Expected: FAIL — current demo has no tabs or sliders
+
+**Step 3: Write the new `_build_demo` function**
+
+Replace `_build_demo` in `app.py`:
+
+```python
+def _build_demo() -> gr.Blocks:
+    _, language_names = _build_language_mappings()
+
+    with gr.Blocks(title="MADLAD-400 Translation") as demo:
+        gr.Markdown(
+            "# MADLAD-400 Translation\n"
+            "Translate English into 22 production-ready languages using Google's MADLAD-400 3B model. "
+            "[Paper](https://arxiv.org/pdf/2309.04662)"
+        )
+
+        with gr.Row():
+            # --- Sidebar ---
+            with gr.Column(scale=1, min_width=250):
+                gr.Markdown("### Settings")
+
+                target_language = gr.Dropdown(
+                    choices=language_names,
+                    value="French",
+                    label="Target language",
+                )
+                max_new_tokens = gr.Slider(
+                    minimum=1, maximum=1024, value=512, step=1, label="Max new tokens"
+                )
+                num_beams = gr.Slider(minimum=1, maximum=10, value=1, step=1, label="Num beams")
+                temperature = gr.Slider(minimum=0.1, maximum=2.0, value=1.0, step=0.1, label="Temperature")
+
+            # --- Main area ---
+            with gr.Column(scale=3):
+                with gr.Tab("Single"):
+                    with gr.Row():
+                        input_text = gr.Textbox(
+                            label="English",
+                            placeholder="Enter English text here",
+                            lines=4,
+                        )
+                        output_text = gr.Textbox(
+                            label="Translation",
+                            lines=4,
+                            buttons=["copy"],
+                            interactive=False,
+                        )
+
+                    single_btn = gr.Button("Translate", variant="primary")
+
+                    single_btn.click(
+                        fn=translate,
+                        inputs=[input_text, target_language, max_new_tokens, num_beams, temperature],
+                        outputs=output_text,
+                    )
+
+                    gr.Examples(
+                        examples=[
+                            ["Hello, how are you today?", "French"],
+                            ["The weather is beautiful.", "Spanish"],
+                            ["Thank you very much.", "German"],
+                            ["Where is the train station?", "Portuguese"],
+                        ],
+                        inputs=[input_text, target_language],
+                    )
+
+                with gr.Tab("Batch"):
+                    gr.Markdown(
+                        "Upload a `.txt` file (one sentence per line) or a `.csv` file with a `text` column."
+                    )
+                    batch_input = gr.File(label="Upload file", file_types=[".txt", ".csv"])
+                    batch_output = gr.File(label="Download translations", interactive=False)
+
+                    batch_btn = gr.Button("Translate", variant="primary")
+
+                    batch_btn.click(
+                        fn=translate_batch,
+                        inputs=[batch_input, target_language, max_new_tokens, num_beams, temperature],
+                        outputs=batch_output,
+                    )
+
+    return demo
+```
+
+**Step 4: Run tests to verify they pass**
+
+Run: `pytest tests/test_app.py::test_demo_has_sidebar_and_tabs tests/test_app.py::test_demo_has_three_sliders tests/test_app.py::test_demo_has_two_tabs -v`
+Expected: PASS
+
+**Step 5: Run all fast tests to check for regressions**
+
+Run: `pytest -m "not slow" -v`
+Expected: All PASS
+
+**Step 6: Run linter**
+
+Run: `ruff check app.py tests/test_app.py`
+Expected: No errors
+
+**Step 7: Commit**
+
+```bash
+git add app.py tests/test_app.py
+git commit -m "feat: rebuild UI with sidebar and tabbed Single/Batch layout"
+```
+
+---
+
+### Task 5: Update CLAUDE.md and README.md
+
+**Files:**
+- Modify: `CLAUDE.md`
+- Modify: `README.md`
+
+**Step 1: Update CLAUDE.md**
+
+In the **Architecture** section for `app.py`, update the description to reflect the new layout:
+
+Replace:
+> **`app.py`** — Single-file application. Uses `@lru_cache` for lazy loading...
+
+With:
+> **`app.py`** — Single-file application with two-column layout: a settings sidebar (target language + generation parameters) and a tabbed main area (Single text / Batch file translation). Uses `@lru_cache` for lazy loading of the `google/madlad400-3b-mt` tokenizer and model (no download on import). Uses `float16` on CUDA, `float32` on CPU. MPS is not supported (produces garbage output with T5 models). Translation prepends a language token with a space to the input text (e.g., `<2fr> Hello`) before tokenization and generation. The `@spaces.GPU` decorator allocates GPU on HF Spaces infrastructure. Batch mode accepts `.txt` (one sentence per line) and `.csv` (requires `text` column) files.
+
+**Step 2: Update README.md if it references the UI**
+
+Check README.md for any UI-specific text and update accordingly.
+
+**Step 3: Commit**
+
+```bash
+git add CLAUDE.md README.md
+git commit -m "docs: update CLAUDE.md and README.md for new UI layout"
+```
+
+---
+
+### Task 6: Final verification
+
+**Step 1: Run all fast tests**
+
+Run: `pytest -m "not slow" -v`
+Expected: All PASS
+
+**Step 2: Run linter and formatter**
+
+Run: `ruff check . && ruff format --check .`
+Expected: No errors
+
+**Step 3: Run type checker**
+
+Run: `ty check`
+Expected: No new errors
+
+**Step 4: Manual smoke test**
+
+Run: `python app.py`
+Expected: App launches at http://localhost:7860 with sidebar and tabs visible. Verify:
+- Sidebar shows: target language dropdown, 3 sliders with correct defaults/ranges
+- Single tab: input/output textboxes, translate button, examples
+- Batch tab: file upload, download area, translate button