fix: greedy-decode by default; apply review cleanups

From a multi-agent review of the session's changes:

- translate(): greedy-decode by default. Previously num_beams==1 always
set do_sample=True, so the default/public /translate path sampled at
temperature 1.0 -> non-deterministic, lower-quality MT. Now sampling is
enabled only when the user sets a non-default temperature; beam search
still ignores it. New test locks both branches.
- tests: assert _estimate_duration mirrors translate()'s signature (the
ZeroGPU duration-callable contract); widen the requirements-exclusion
regex to also split on '[' and ',' so gradio[extra] can't slip through.
- _translate_with_loading: tighten return annotation to
Generator[tuple[object, object], None, None].

51 fast / 61 total. ruff + ty clean. Docs (CLAUDE.md, README) synced.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

CLAUDE.md

@@ -25,8 +25,8 @@ uv run ruff format .
 uv run ty check
 
 # Test
-uv run pytest                     # all 59 tests (slow require CUDA + model download)
-uv run pytest -m "not slow"       # 49 fast tests only
+uv run pytest                     # all 61 tests (slow require CUDA + model download)
+uv run pytest -m "not slow"       # 51 fast tests only
 uv run pytest -m slow             # 10 model tests only (CUDA only)
 
 # Generate language mapping (dev only)
@@ -35,13 +35,13 @@ uv run scripts/generate_langmap.py <path-to-paper.pdf>
 
 ## Architecture
 
-**`app.py`** — Single-file application with a Google Translate-style layout: top row has two symmetric, filterable, region-sorted language dropdowns (source defaults to "English (en)", target defaults to "French (fr)") with a swap button ("⇄") between them; below that, input textbox (autofocused) and output textbox with copy button side by side. The Translate button spans full width below both textboxes (shows "Translating..." during processing). Ctrl+Enter submits from the input. The model auto-detects source language; the source dropdown is for user reference and the swap button only. Uses `@lru_cache` for lazy loading of the `google/madlad400-3b-mt` tokenizer and model. On ZeroGPU (`SPACES_ZERO_GPU=1`), `_maybe_eager_load()` places the model at module scope so the `spaces` hijack can pack weights and stream them into workers for fast cold starts; off-ZeroGPU (local, tests, cpu-basic) it stays lazy, so importing the app never downloads the model. Uses `bfloat16` on CUDA (T5/MADLAD is numerically unstable in `float16` — fp16's narrow range overflows to inf/NaN; bf16 is the format T5 was trained in), `float32` on CPU. MPS is not supported (produces garbage output with T5 models). Translation prepends a target 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; its `duration` is a callable (`_estimate_duration`) that scales the GPU reservation with `max_new_tokens × num_beams` (capped at 120s). The submit handler exposes a stable `/translate` API endpoint; the swap and Translate-button handlers are `api_visibility="private"`. Only `/translate` is public.
+**`app.py`** — Single-file application with a Google Translate-style layout: top row has two symmetric, filterable, region-sorted language dropdowns (source defaults to "English (en)", target defaults to "French (fr)") with a swap button ("⇄") between them; below that, input textbox (autofocused) and output textbox with copy button side by side. The Translate button spans full width below both textboxes (shows "Translating..." during processing). Ctrl+Enter submits from the input. The model auto-detects source language; the source dropdown is for user reference and the swap button only. Uses `@lru_cache` for lazy loading of the `google/madlad400-3b-mt` tokenizer and model. On ZeroGPU (`SPACES_ZERO_GPU=1`), `_maybe_eager_load()` places the model at module scope so the `spaces` hijack can pack weights and stream them into workers for fast cold starts; off-ZeroGPU (local, tests, cpu-basic) it stays lazy, so importing the app never downloads the model. Uses `bfloat16` on CUDA (T5/MADLAD is numerically unstable in `float16` — fp16's narrow range overflows to inf/NaN; bf16 is the format T5 was trained in), `float32` on CPU. MPS is not supported (produces garbage output with T5 models). Translation prepends a target language token with a space to the input text (e.g., `<2fr> Hello`) before tokenization and generation. Decoding is greedy by default (deterministic); a non-default `temperature` enables sampling, and `num_beams > 1` uses beam search. The `@spaces.GPU` decorator allocates GPU on HF Spaces infrastructure; its `duration` is a callable (`_estimate_duration`) that scales the GPU reservation with `max_new_tokens × num_beams` (capped at 120s). The submit handler exposes a stable `/translate` API endpoint; the swap and Translate-button handlers are `api_visibility="private"`. Only `/translate` is public.
 
 **`langmap/`** — Package with `langid_mapping.py`, mapping 418 language tokens to `{"name": ..., "region": ...}` dicts. Auto-generated by `scripts/generate_langmap.py` from Table 9 (Section A.1) of the MADLAD-400 paper. Available languages at runtime are the intersection of this mapping and the model's vocabulary.
 
 **`scripts/`** — `generate_langmap.py` parses the MADLAD-400 paper PDF (Table 9, pages 16-22) using pdfplumber and generates the static language mapping with region assignments. Dev-only tool; requires `requirements-dev.txt` dependencies.
 
-**`tests/`** — 59 tests (49 fast, 10 slow). `test_langmap.py` has 10 fast tests for mapping validation (dict shape, regions, spot-checks). `test_app.py` has 39 fast tests (signatures, device fallback, bfloat16/float32 dtype selection, ZeroGPU eager-load gating, GPU duration estimator, `requirements.txt` excludes platform packages, UI layout with symmetric dropdowns, swap button, textbox config including toolbar buttons and input autofocus, handler wiring, stable `translate` API endpoint with UI-only handlers kept private, no HTML elements, locale codes, no title) and 10 slow tests (translation with various parameters, language mapping). Slow tests require CUDA and model download; auto-skipped without CUDA.
+**`tests/`** — 61 tests (51 fast, 10 slow). `test_langmap.py` has 10 fast tests for mapping validation (dict shape, regions, spot-checks). `test_app.py` has 41 fast tests (signatures, device fallback, bfloat16/float32 dtype selection, ZeroGPU eager-load gating, GPU duration estimator and its signature-mirror contract, greedy-by-default decoding, `requirements.txt` excludes platform packages, UI layout with symmetric dropdowns, swap button, textbox config including toolbar buttons and input autofocus, handler wiring, stable `translate` API endpoint with UI-only handlers kept private, no HTML elements, locale codes, no title) and 10 slow tests (translation with various parameters, language mapping). Slow tests require CUDA and model download; auto-skipped without CUDA.
 
 ## Tooling
 

README.md

@@ -39,6 +39,6 @@ The Gradio interface launches at `http://localhost:7860`.
 uv run ruff check .             # lint
 uv run ruff format .            # format
 uv run ty check                 # type check
-uv run pytest -m "not slow"     # 49 fast tests
-uv run pytest                   # all 59 tests (slow require CUDA + model download)
+uv run pytest -m "not slow"     # 51 fast tests
+uv run pytest                   # all 61 tests (slow require CUDA + model download)
 ```

app.py

@@ -116,7 +116,9 @@ def translate(
     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:
+    # Greedy by default (deterministic, higher-quality MT). Only sample when the user
+    # explicitly sets a non-default temperature; beam search (num_beams > 1) ignores it.
+    if num_beams == 1 and temperature != 1.0:
         generate_kwargs["do_sample"] = True
         generate_kwargs["temperature"] = temperature
 
@@ -135,7 +137,7 @@ def translate(
 def _translate_with_loading(
     text: str,
     target_language_name: str,
-) -> Generator[tuple, None, None]:
+) -> Generator[tuple[object, object], None, None]:
     yield gr.update(value="Translating...", interactive=False), gr.update()
     result = translate(text, target_language_name)
     yield gr.update(value="Translate", interactive=True), result

tests/test_app.py

@@ -136,6 +136,43 @@ def test_estimate_duration_is_input_aware_and_capped():
     assert all(isinstance(d, int) for d in (small, default, heavy))
 
 
+def test_estimate_duration_mirrors_translate_signature():
+    """ZeroGPU calls the duration callable with translate()'s exact args, so _estimate_duration
+    must mirror translate()'s parameter names and order (the load-bearing ZeroGPU contract)."""
+    import inspect
+
+    import app
+
+    assert list(inspect.signature(app._estimate_duration).parameters) == list(
+        inspect.signature(app.translate).parameters
+    )
+
+
+def test_translate_greedy_by_default_samples_on_custom_temperature():
+    """num_beams=1 should greedy-decode at the default temperature (deterministic) and enable
+    sampling only when the user sets a non-default temperature."""
+    import app
+
+    def run(temperature):
+        model = MagicMock()
+        model.device = torch.device("cpu")
+        model.generate.return_value = [[0]]
+        tokenizer = MagicMock()
+        tokenizer.decode.return_value = "out"
+        with (
+            patch("app._load_model", return_value=model),
+            patch("app._load_tokenizer", return_value=tokenizer),
+            patch("app._build_language_mappings", return_value=({"French (fr)": "<2fr>"}, ["French (fr)"])),
+        ):
+            app.translate("Hello", "French (fr)", temperature=temperature)
+        return model.generate.call_args.kwargs
+
+    greedy = run(1.0)
+    sampled = run(0.5)
+    assert not greedy.get("do_sample", False), "default temperature should greedy-decode"
+    assert sampled.get("do_sample") is True and sampled["temperature"] == 0.5
+
+
 def test_requirements_excludes_platform_packages():
     """gradio and spaces are provided by the HF Spaces runtime on every tier; pinning them in
     requirements.txt drifts the ZeroGPU runtime, so they must stay out (see requirements-dev.txt)."""
@@ -144,7 +181,7 @@ def test_requirements_excludes_platform_packages():
 
     reqs = Path(__file__).resolve().parent.parent / "requirements.txt"
     names = {
-        re.split(r"[<>=~!;\s]", line.strip())[0].lower()
+        re.split(r"[<>=~!;\[\s,]", line.strip())[0].lower()
         for line in reqs.read_text().splitlines()
         if line.strip() and not line.strip().startswith("#")
     }