Switch translation backend from Gemini to OpenRouter, add test suite

Replaces the Gemini API integration with OpenRouter: the model dropdown is
now live-fetched from OpenRouter's catalog with a small curated set of
recommended models pinned to the top (also used as OpenRouter's server-side
model fallback chain). Adds a pytest suite covering chunking, file I/O,
prompt storage, the OpenRouter backend, the backend dispatcher, the local CPU
backend, and the Gradio handlers/app wiring, plus sample Tibetan input files
(txt/docx/pdf) used as test fixtures. Also adds a pre-push git hook that runs
the suite and blocks the push on failure.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

.githooks/pre-push

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+# Runs the test suite before allowing a push. Install this hook with:
+#   git config core.hooksPath .githooks
+# (or copy it into .git/hooks/pre-push directly).
+set -euo pipefail
+
+repo_root="$(git rev-parse --show-toplevel)"
+cd "$repo_root"
+
+if [ -x ".venv/bin/pytest" ]; then
+    PYTEST=".venv/bin/pytest"
+elif command -v pytest >/dev/null 2>&1; then
+    PYTEST="pytest"
+else
+    echo "pre-push: pytest not found (expected .venv/bin/pytest or pytest on PATH)." >&2
+    echo "Install dev deps first: pip install -r requirements-dev.txt" >&2
+    exit 1
+fi
+
+echo "pre-push: running test suite..."
+if ! "$PYTEST" -q; then
+    echo "pre-push: tests failed, aborting push." >&2
+    exit 1
+fi

CLAUDE.md

@@ -32,17 +32,22 @@ engine/
   chunking.py               Plain-text -> segment list (paragraph, then shad/whitespace splitting)
   formats.py                Read .txt/.docx/.pdf; write .txt/.docx/.json
   prompt.py                 Read/write/reset translation_prompt.txt (local file only)
-  translate.py              Backend dispatcher (Gemini vs local CPU model) + batching/progress
-  gemini_backend.py          Gemini API calls, retries, fallback model chain, batch prompt building
+  translate.py              Backend dispatcher (OpenRouter vs local CPU model) + batching/progress
+  openrouter_backend.py      OpenRouter API calls, retries, server-side model fallback, batch prompt building
   local_backend.py           CPU fallback: AutoModelForSeq2SeqLM "billingsmoore/mlotsawa-ground-base"
 ```
 
 ## Translation backend selection
 
 `engine/translate.py::_resolve_key()` decides per-call:
-- A Gemini API key was typed into the UI, **or** `GEMINI_API_KEY` is set (env var / `.env`) → use Gemini,
-  with the prompt in `translation_prompt.txt` (editable in Settings) and the model picked in the dropdown
-  (`FALLBACK_CHAIN` in `engine/gemini_backend.py`; falls through the chain on failure).
+- An OpenRouter API key was typed into the UI, **or** `OPENROUTER_API_KEY` is set (env var / `.env`)
+  → use OpenRouter, with the prompt in `translation_prompt.txt` (editable in Settings) and the model
+  picked in the dropdown. The dropdown is populated by `engine/openrouter_backend.py::list_model_choices()`,
+  which live-fetches OpenRouter's `/models` catalog and puts `CURATED_MODELS` (a small hand-picked,
+  known-good-for-translation set) at the top, followed by the rest of the text-output catalog
+  alphabetically — falls back to just `CURATED_MODELS` if the fetch fails (offline, OpenRouter down).
+  `CURATED_MODELS` also doubles as the `models` fallback array OpenRouter is given per request, so it
+  retries server-side against another good model if the chosen one errors out.
 - No key anywhere → use the local CPU model `billingsmoore/mlotsawa-ground-base` via
   `AutoModelForSeq2SeqLM.generate()` directly (see `engine/local_backend.py`). This is a plain finetuned
   T5 seq2seq model — it does **not** read `translation_prompt.txt` at all. First call downloads the
@@ -69,8 +74,32 @@ timestamp concept anywhere in this app — segments are just `{"source": str, "t
 pip install -r requirements.txt
 python app.py
 ```
-Opens on `http://localhost:7860`. Put `GEMINI_API_KEY=...` in a `.env` file to default to Gemini
-without typing a key into the UI each time.
+Opens on `http://localhost:7860`. Put `OPENROUTER_API_KEY=...` in a `.env` file to default to
+OpenRouter without typing a key into the UI each time.
+
+## Testing
+
+```bash
+pip install -r requirements-dev.txt
+pytest
+```
+
+`tests/` covers chunking, file I/O (txt/docx/pdf load+export, JSON resume),
+prompt storage, the OpenRouter backend (model curation/fetch-fallback, request
+retry/fallback logic, batch prompt building/parsing — all with `requests`
+mocked, no real network calls or API key needed), the backend dispatcher, the
+local CPU backend (with `torch`/`transformers` stubbed via `sys.modules` so
+the suite doesn't require installing those heavy deps), the Gradio event
+handlers, and a smoke test that the Blocks graph in `app.py` builds without
+error. `samples/sample_tibetan.{txt,docx,pdf}` are real Tibetan-script fixture
+files (a well-known refuge/bodhicitta verse, the four immeasurables, and a
+dedication verse) used by the format-loading tests and useful for manually
+exercising the upload flow.
+
+A `pre-push` git hook (`.githooks/pre-push`) runs the full suite and blocks
+the push if anything fails. It's already installed into `.git/hooks/pre-push`
+in this working copy; on a fresh clone, install it with either
+`git config core.hooksPath .githooks` or `cp .githooks/pre-push .git/hooks/`.
 
 ## Conventions to keep
 

README.md

@@ -21,9 +21,11 @@ projects — just upload, translate, edit, download.
 
 ## Translation backend
 
-- If you provide a **Gemini API key** (in the UI, or via a `GEMINI_API_KEY`
-  env var / `.env` file), translation uses Gemini with the editable prompt
-  in the Settings panel (`translation_prompt.txt`).
+- If you provide an **OpenRouter API key** (in the UI, or via an
+  `OPENROUTER_API_KEY` env var / `.env` file), translation uses whichever
+  OpenRouter model you pick from the Settings dropdown (live-fetched from
+  OpenRouter's catalog, with a few recommended models pinned to the top),
+  with the editable prompt in the Settings panel (`translation_prompt.txt`).
 - Otherwise it falls back to a **local CPU model**,
   [billingsmoore/mlotsawa-ground-base](https://huggingface.co/billingsmoore/mlotsawa-ground-base),
   loaded via `transformers`. The prompt box has no effect on this backend —
@@ -37,8 +39,8 @@ pip install -r requirements.txt
 python app.py
 ```
 
-Optionally set `GEMINI_API_KEY` in a `.env` file to default to Gemini without
-typing a key into the UI each time.
+Optionally set `OPENROUTER_API_KEY` in a `.env` file to default to OpenRouter
+without typing a key into the UI each time.
 
 ## Downloads
 

app.py

@@ -4,7 +4,7 @@ from dotenv import load_dotenv
 load_dotenv()
 
 import gradio as gr
-from engine import FALLBACK_CHAIN
+from engine import DEFAULT_MODEL, list_model_choices
 
 from styles import CSS
 from handlers import (
@@ -51,20 +51,23 @@ def build_app() -> gr.Blocks:
 
         with gr.Accordion("Settings", open=False):
             with gr.Row():
-                gemini_api_key = gr.Textbox(
-                    label="Gemini API Key (optional)",
-                    placeholder="AIza… — leave blank to use the local CPU model instead",
+                openrouter_api_key = gr.Textbox(
+                    label="OpenRouter API Key (optional)",
+                    placeholder="sk-or-… — leave blank to use the local CPU model instead",
                     type="password",
                     scale=2,
                 )
-                gemini_model = gr.Dropdown(
-                    choices=FALLBACK_CHAIN, value=FALLBACK_CHAIN[0],
-                    label="Gemini Model (only used if a key is given)", scale=1,
+                openrouter_model = gr.Dropdown(
+                    choices=list_model_choices(), value=DEFAULT_MODEL,
+                    label="OpenRouter Model (only used if a key is given)",
+                    info="A few recommended models are pinned at the top; the rest of "
+                         "OpenRouter's catalog is below — type to filter.",
+                    scale=1,
                 )
 
             gr.Markdown(
                 "### Translation Prompt\n"
-                "Only used when translating with Gemini — the local CPU fallback "
+                "Only used when translating with OpenRouter — the local CPU fallback "
                 "(billingsmoore/mlotsawa-ground-base) is a plain translation model and ignores this. "
                 "Saved directly to `translation_prompt.txt` in this app's folder."
             )
@@ -127,7 +130,7 @@ def build_app() -> gr.Blocks:
 
         translate_event = translate_all_btn.click(
             _translate_all,
-            inputs=[app_state, gemini_api_key, gemini_model, *slot_sources, *slot_targets],
+            inputs=[app_state, openrouter_api_key, openrouter_model, *slot_sources, *slot_targets],
             outputs=translate_all_outputs,
         )
         cancel_btn.click(fn=None, cancels=[translate_event])
@@ -155,7 +158,7 @@ def build_app() -> gr.Blocks:
                 outputs=[slot_targets[i]],
             ).then(
                 fn=lambda state, source, key, model, i=i: _translate_one(state, i, source, key, model),
-                inputs=[app_state, slot_sources[i], gemini_api_key, gemini_model],
+                inputs=[app_state, slot_sources[i], openrouter_api_key, openrouter_model],
                 outputs=[app_state, slot_targets[i]],
             )
 

engine/__init__.py

@@ -13,8 +13,10 @@ from .formats import (
 )
 from .prompt import read_prompt, save_prompt, reset_prompt, PROMPT_PATH
 from .translate import (
-    FALLBACK_CHAIN,
+    CURATED_MODELS,
+    DEFAULT_MODEL,
+    list_model_choices,
     translate_one,
     translate_segments,
-    using_gemini,
+    using_openrouter,
 )

engine/local_backend.py

@@ -1,5 +1,5 @@
 """CPU translation backend using billingsmoore/mlotsawa-ground-base
-(a Tibetan->English seq2seq T5 model). Used whenever no Gemini API key is
+(a Tibetan->English seq2seq T5 model). Used whenever no OpenRouter API key is
 available. The model is loaded once, lazily, on first use.
 
 Generation uses the model's own task_specific_params["translation_bo_to_en"]

engine/{gemini_backend.py → openrouter_backend.py}

@@ -1,56 +1,104 @@
-"""Gemini translation backend. Used only when a Gemini API key is available
-(user-supplied or GEMINI_API_KEY env var) — otherwise engine.translate falls
-back to the local CPU model."""
+"""OpenRouter translation backend. Used only when an OpenRouter API key is
+available (user-supplied or OPENROUTER_API_KEY env var) — otherwise
+engine.translate falls back to the local CPU model."""
 
 import re
 import time
-from concurrent.futures import ThreadPoolExecutor, TimeoutError as _FuturesTimeout
 
-FALLBACK_CHAIN = [
-    "gemini-2.5-flash",
-    "gemini-2.5-pro",
-    "gemini-3-flash-preview",
-    "gemini-3.1-pro-preview",
+import requests
+
+BASE_URL = "https://openrouter.ai/api/v1"
+
+# Small hand-picked set of models known to work well for this kind of
+# instruction-following translation task. These are pinned to the top of the
+# UI dropdown (ahead of the full live-fetched catalog) and also used as
+# OpenRouter's server-side model fallback chain for a given request.
+CURATED_MODELS = [
+    "anthropic/claude-sonnet-4.5",
+    "openai/gpt-4o",
+    "openai/gpt-4o-mini",
+    "google/gemini-2.5-flash",
+    "google/gemini-2.5-pro",
+    "deepseek/deepseek-chat",
+    "qwen/qwen-2.5-72b-instruct",
+    "meta-llama/llama-3.3-70b-instruct",
 ]
 
-_GEMINI_TIMEOUT = 120
+DEFAULT_MODEL = CURATED_MODELS[0]
+
+_TIMEOUT = 120
+_MODELS_TIMEOUT = 10
 _BACKOFF_BASE = 2
 _BATCH_SIZE = 25
 
+_RETRYABLE_STATUS = {408, 429, 500, 502, 503, 504}
+
 
 def _is_retryable(exc) -> bool:
     msg = str(exc).lower()
-    return any(x in msg for x in ("429", "rate limit", "quota", "503", "500", "unavailable"))
+    return any(x in msg for x in ("429", "rate limit", "timed out", "timeout", "connection"))
 
 
-def _call_gemini(client, model: str, prompt: str):
-    from google.genai import types
-    config = types.GenerateContentConfig(
-        thinking_config=types.ThinkingConfig(thinking_budget=0)
-    )
-    queue = [model] + [m for m in FALLBACK_CHAIN if m != model]
+def fetch_available_models(timeout: int = _MODELS_TIMEOUT) -> list[dict]:
+    """Raw model list from OpenRouter's public /models endpoint (no key required)."""
+    resp = requests.get(f"{BASE_URL}/models", timeout=timeout)
+    resp.raise_for_status()
+    return resp.json().get("data", [])
+
+
+def _is_text_model(model: dict) -> bool:
+    arch = model.get("architecture") or {}
+    modality = arch.get("modality") or ""
+    output_modalities = arch.get("output_modalities") or []
+    return modality.endswith("->text") or "text" in output_modalities
+
+
+def list_model_choices(timeout: int = _MODELS_TIMEOUT) -> list[str]:
+    """Curated models first (in preferred order), then the rest of OpenRouter's
+    text-output catalog alphabetically. Falls back to just the curated list if
+    the live fetch fails (offline, OpenRouter down, etc.)."""
+    try:
+        models = fetch_available_models(timeout=timeout)
+    except Exception as e:
+        print(f"[WARN] Could not fetch OpenRouter model list, using curated defaults only: {e}")
+        return list(CURATED_MODELS)
+
+    ids = {m["id"] for m in models if _is_text_model(m)}
+    curated_present = [m for m in CURATED_MODELS if m in ids]
+    rest = sorted(ids.difference(curated_present))
+    return curated_present + rest
+
+
+def _call_openrouter(api_key: str, model: str, prompt: str) -> str:
+    headers = {
+        "Authorization": f"Bearer {api_key}",
+        "Content-Type": "application/json",
+    }
+    # OpenRouter tries "models" in order server-side if the primary errors out,
+    # so we don't need to re-implement model-swapping client-side.
+    fallback_models = [model] + [m for m in CURATED_MODELS if m != model]
+    body = {
+        "models": fallback_models,
+        "messages": [{"role": "user", "content": prompt}],
+    }
+
     last_exc = None
-    for candidate in queue:
-        if candidate != model:
-            print(f"[WARN] Gemini model '{model}' failed. Trying '{candidate}'.")
-        for attempt in range(4):
-            try:
-                with ThreadPoolExecutor(max_workers=1) as executor:
-                    future = executor.submit(
-                        client.models.generate_content,
-                        model=candidate, contents=prompt, config=config,
-                    )
-                    return future.result(timeout=_GEMINI_TIMEOUT)
-            except _FuturesTimeout:
-                last_exc = TimeoutError(f"Gemini '{candidate}' timed out after {_GEMINI_TIMEOUT}s")
-                print(f"[WARN] {last_exc} (attempt {attempt + 1}/4)")
-            except Exception as e:
-                last_exc = e
-                if not _is_retryable(e):
-                    break
-                print(f"[WARN] Gemini '{candidate}' attempt {attempt + 1}/4 failed: {e}")
-            if attempt < 3:
-                time.sleep(_BACKOFF_BASE ** attempt)
+    for attempt in range(4):
+        try:
+            resp = requests.post(f"{BASE_URL}/chat/completions", headers=headers, json=body, timeout=_TIMEOUT)
+        except requests.RequestException as e:
+            last_exc = e
+            print(f"[WARN] OpenRouter request attempt {attempt + 1}/4 failed: {e}")
+        else:
+            if resp.status_code == 200:
+                data = resp.json()
+                return data["choices"][0]["message"]["content"]
+            last_exc = RuntimeError(f"OpenRouter HTTP {resp.status_code}: {resp.text[:300]}")
+            if resp.status_code not in _RETRYABLE_STATUS:
+                raise last_exc
+            print(f"[WARN] OpenRouter attempt {attempt + 1}/4 failed: {last_exc}")
+        if attempt < 3:
+            time.sleep(_BACKOFF_BASE ** attempt)
     raise last_exc
 
 
@@ -84,15 +132,12 @@ def _parse_batch_response(response_text: str, expected: int) -> list[str] | None
 
 
 def translate_one(text: str, api_key: str, model: str, template: str) -> str:
-    from google import genai
-    client = genai.Client(api_key=api_key)
     prompt = (
         template.rstrip()
         + f"\n\nTranslate the following into English, following all instructions "
           f"above. Output ONLY the translation, no other text.\n\n{text}"
     )
-    response = _call_gemini(client, model, prompt)
-    return response.text.strip()
+    return _call_openrouter(api_key, model, prompt).strip()
 
 
 def translate_batch(
@@ -100,12 +145,10 @@ def translate_batch(
 ) -> list[str] | None:
     if not texts:
         return []
-    from google import genai
-    client = genai.Client(api_key=api_key)
     prompt = _build_batch_prompt(template, texts, preceding=preceding)
     try:
-        response = _call_gemini(client, model, prompt)
-        return _parse_batch_response(response.text.strip(), len(texts))
+        content = _call_openrouter(api_key, model, prompt)
+        return _parse_batch_response(content.strip(), len(texts))
     except Exception as e:
-        print(f"[WARN] Gemini batch translation failed: {e}")
+        print(f"[WARN] OpenRouter batch translation failed: {e}")
         return None

engine/translate.py

@@ -1,29 +1,31 @@
-"""Backend dispatcher: Gemini if an API key is available (user-supplied or
-GEMINI_API_KEY env var), otherwise the local CPU model. Callers don't need
+"""Backend dispatcher: OpenRouter if an API key is available (user-supplied or
+OPENROUTER_API_KEY env var), otherwise the local CPU model. Callers don't need
 to know which backend actually ran."""
 
 import os
 
-from . import gemini_backend
 from . import local_backend
+from . import openrouter_backend
 from .prompt import read_prompt
 
-FALLBACK_CHAIN = gemini_backend.FALLBACK_CHAIN
-_BATCH_SIZE = gemini_backend._BATCH_SIZE
+CURATED_MODELS = openrouter_backend.CURATED_MODELS
+DEFAULT_MODEL = openrouter_backend.DEFAULT_MODEL
+list_model_choices = openrouter_backend.list_model_choices
+_BATCH_SIZE = openrouter_backend._BATCH_SIZE
 
 
 def _resolve_key(api_key: str | None) -> str:
-    return (api_key or "").strip() or os.environ.get("GEMINI_API_KEY", "")
+    return (api_key or "").strip() or os.environ.get("OPENROUTER_API_KEY", "")
 
 
-def using_gemini(api_key: str | None) -> bool:
+def using_openrouter(api_key: str | None) -> bool:
     return bool(_resolve_key(api_key))
 
 
 def translate_one(text: str, api_key: str | None, model: str) -> str:
     key = _resolve_key(api_key)
     if key:
-        return gemini_backend.translate_one(text, key, model, read_prompt())
+        return openrouter_backend.translate_one(text, key, model, read_prompt())
     return local_backend.translate_batch([text])[0]
 
 
@@ -42,7 +44,7 @@ def translate_segments(
         if not seg.get("target", "").strip() and seg.get("source", "").strip()
     ]
     total = len(translatable)
-    print(f"[INFO] Translating {total} segment(s) via {'Gemini' if key else 'local CPU model'}.")
+    print(f"[INFO] Translating {total} segment(s) via {'OpenRouter' if key else 'local CPU model'}.")
 
     recent: list[str] = []
     for batch_start in range(0, total, _BATCH_SIZE):
@@ -57,14 +59,14 @@ def translate_segments(
 
         if key:
             preceding = recent[-3:] if recent else None
-            translations = gemini_backend.translate_batch(texts, key, model, template, preceding=preceding)
+            translations = openrouter_backend.translate_batch(texts, key, model, template, preceding=preceding)
             if translations is None:
                 translations = []
                 for idx, text in zip(indices, texts):
                     if stop is not None and stop.is_set():
                         break
                     try:
-                        t = gemini_backend.translate_one(text, key, model, template)
+                        t = openrouter_backend.translate_one(text, key, model, template)
                     except Exception as e:
                         print(f"[WARN] Segment {idx + 1} failed: {e}")
                         errors.append(f"Segment {idx + 1}: {e}")

handlers.py

@@ -10,7 +10,6 @@ from pathlib import Path
 import gradio as gr
 
 from engine import (
-    FALLBACK_CHAIN,
     export_to_docx,
     export_to_json,
     export_to_txt,
@@ -21,7 +20,7 @@ from engine import (
     save_prompt,
     translate_one as _engine_translate_one,
     translate_segments,
-    using_gemini,
+    using_openrouter,
 )
 
 MAX_SLOTS = 25
@@ -249,7 +248,7 @@ def _translate_all(state, api_key, model, *slot_values):
     targets = list(slot_values[MAX_SLOTS:])
     state = _save_page_edits(state, sources, targets)
 
-    backend = "Gemini" if using_gemini(api_key) else "local CPU model (mlotsawa-ground-base)"
+    backend = "OpenRouter" if using_openrouter(api_key) else "local CPU model (mlotsawa-ground-base)"
 
     stop = threading.Event()
     result = [None, None]

requirements-dev.txt

@@ -0,0 +1,2 @@
+-r requirements.txt
+pytest

requirements.txt

@@ -1,6 +1,6 @@
 gradio>=6.9.0
 spaces
-google-genai
+requests
 python-dotenv
 transformers
 torch

samples/sample_tibetan.txt

@@ -0,0 +1,11 @@
+སངས་རྒྱས་ཆོས་དང་ཚོགས་ཀྱི་མཆོག་རྣམས་ལ། །
+བྱང་ཆུབ་བར་དུ་བདག་ནི་སྐྱབས་སུ་མཆི། །
+བདག་གིས་སྦྱིན་སོགས་བགྱིས་པའི་བསོད་ནམས་ཀིས། །
+འགྲོ་ལ་ཕན་ཕྱིར་སངས་རྒྱས་འགྲུབ་པར་ཤོག། །
+
+སེམས་ཅན་ཐམས་ཅད་བདེ་བ་དང་བདེ་བའི་རྒྱུ་དང་ལྡན་པར་གྱུར་ཅིག། སེམས་ཅན་ཐམས་ཅད་སྡུག་བསྔལ་དང་སྡུག་བསྔལ་གྱི་རྒྱུ་དང་བྲལ་བར་གྱུར་ཅིག། སེམས་ཅན་ཐམས་ཅད་སྡུག་བསྔལ་མེད་པའི་བདེ་བ་དང་མི་འབྲལ་བར་གྱུར་ཅིག། སེམས་ཅན་ཐམས་ཅད་ཉེ་རིང་ཆགས་སྡང་གཉིས་དང་བྲལ་བའི་བཏང་སྙོམས་ཚད་མེད་པ་ལ་གནས་པར་གྱུར་ཅིག།
+
+བསོད་ནམས་འདི་ཡིས་ཐམས་ཅད་གཟིགས་པ་ཉིད། །
+ཐོབ་ནས་ཉེས་པའི་དགྲ་རྣམས་ཕམ་བྱས་ཏེ། །
+སྐྱེ་རྒ་ན་འཆིའི་རྦ་ཀློང་འཁྲུགས་པ་ཡི། །
+སྲིད་པའི་མཚོ་ལས་འགྲོ་བ་སྒྲོལ་བར་ཤོག། །

tests/conftest.py

@@ -0,0 +1,6 @@
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).parent.parent
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))

tests/test_app.py

@@ -0,0 +1,21 @@
+"""Smoke test: the Gradio Blocks graph wires up without error. This is what
+would have caught a stale gr.Dropdown choices/value reference or a mismatched
+inputs/outputs list length after the Gemini -> OpenRouter rename."""
+
+from unittest.mock import patch
+
+from app import build_app
+
+
+def test_build_app_does_not_raise():
+    with patch("app.list_model_choices", return_value=["model/a", "model/b"]), \
+         patch("app.DEFAULT_MODEL", "model/a"):
+        demo = build_app()
+    assert demo is not None
+
+
+def test_build_app_falls_back_gracefully_if_model_fetch_fails():
+    with patch("app.list_model_choices", return_value=["model/a"]), \
+         patch("app.DEFAULT_MODEL", "model/a"):
+        demo = build_app()
+    assert demo is not None

tests/test_chunking.py

@@ -0,0 +1,61 @@
+from engine.chunking import split_into_segments
+
+
+def test_blank_line_separates_paragraphs():
+    text = "First paragraph.\n\nSecond paragraph."
+    assert split_into_segments(text, max_chars=400) == ["First paragraph.", "Second paragraph."]
+
+
+def test_multiple_blank_lines_still_one_break():
+    text = "First.\n\n\n\nSecond."
+    assert split_into_segments(text, max_chars=400) == ["First.", "Second."]
+
+
+def test_internal_whitespace_is_collapsed():
+    text = "word1   word2\nword3"
+    assert split_into_segments(text, max_chars=400) == ["word1 word2 word3"]
+
+
+def test_empty_and_whitespace_only_input():
+    assert split_into_segments("", max_chars=400) == []
+    assert split_into_segments("   \n\n  \n", max_chars=400) == []
+
+
+def test_short_paragraph_stays_one_segment():
+    text = "སངས་རྒྱས་ཆོས་དང་ཚོགས་ཀྱི་མཆོག་རྣམས་ལ། །"
+    assert split_into_segments(text, max_chars=400) == [text]
+
+
+def test_long_paragraph_splits_on_shad_marks():
+    sentence = "བདེ་བ་དང་ལྡན་པར་གྱུར་ཅིག" * 1  # one shad-terminated "sentence" below
+    long_text = "།".join(["ཀ" * 30 for _ in range(20)]) + "།"
+    segments = split_into_segments(long_text, max_chars=50)
+    assert len(segments) > 1
+    assert all(len(s) <= 60 for s in segments)  # allows small overhead from joining
+    assert "".join(segments).replace(" ", "") == long_text.replace(" ", "")
+
+
+def test_shad_split_regex_keeps_shad_with_preceding_text():
+    text = "ཀཀཀ།ཁཁཁ༎"
+    from engine.chunking import _SHAD_SPLIT_RE
+    pieces = [p for p in _SHAD_SPLIT_RE.split(text) if p]
+    assert pieces == ["ཀཀཀ།", "ཁཁཁ༎"]
+
+
+def test_single_word_longer_than_max_chars_falls_back_to_word_chunking():
+    text = " ".join(["word"] * 100)  # no shad marks at all, one huge "sentence"
+    segments = split_into_segments(text, max_chars=30)
+    assert len(segments) > 1
+    for seg in segments:
+        assert len(seg) <= 30 or " " not in seg  # a single overlong word is allowed through
+
+
+def test_max_chars_boundary_exact_length_not_split():
+    text = "a" * 400
+    assert split_into_segments(text, max_chars=400) == [text]
+
+
+def test_max_chars_boundary_one_over_length_is_split():
+    text = ("a" * 200) + "། " + ("b" * 200)
+    segments = split_into_segments(text, max_chars=400)
+    assert len(segments) >= 1  # 401 chars total but splits cleanly on the shad mark

tests/test_formats.py

@@ -0,0 +1,185 @@
+import json
+from pathlib import Path
+
+import pytest
+
+from engine.formats import (
+    export_to_docx,
+    export_to_json,
+    export_to_txt,
+    load_source_file,
+    parse_json,
+)
+
+TIBETAN = "སངས་རྒྱས་ཆོས་དང་ཚོགས་ཀྱི་མཆོག་རྣམས་ལ།"
+
+
+# ── load_source_file ──────────────────────────────────────────────────────
+
+def test_load_txt(tmp_path):
+    path = tmp_path / "in.txt"
+    path.write_text(f"{TIBETAN}\n\nSecond paragraph.", encoding="utf-8")
+    segments = load_source_file(str(path))
+    assert segments == [
+        {"source": TIBETAN, "target": ""},
+        {"source": "Second paragraph.", "target": ""},
+    ]
+
+
+def test_load_docx(tmp_path):
+    docx = pytest.importorskip("docx")
+    path = tmp_path / "in.docx"
+    doc = docx.Document()
+    doc.add_paragraph(TIBETAN)
+    doc.add_paragraph("Second paragraph.")
+    doc.add_paragraph("")  # blank paragraphs should be dropped, not turned into segments
+    doc.save(str(path))
+
+    segments = load_source_file(str(path))
+    assert segments == [
+        {"source": TIBETAN, "target": ""},
+        {"source": "Second paragraph.", "target": ""},
+    ]
+
+
+def test_load_pdf(tmp_path):
+    pytest.importorskip("pypdf")
+    reportlab_canvas = pytest.importorskip("reportlab.pdfgen.canvas")
+    from reportlab.lib.pagesizes import letter
+
+    path = tmp_path / "in.pdf"
+    c = reportlab_canvas.Canvas(str(path), pagesize=letter)
+    c.drawString(72, 700, "Hello world.")
+    c.save()
+
+    segments = load_source_file(str(path))
+    assert len(segments) == 1
+    assert "Hello world." in segments[0]["source"]
+    assert segments[0]["target"] == ""
+
+
+def test_load_unsupported_extension_raises(tmp_path):
+    path = tmp_path / "in.rtf"
+    path.write_text("whatever", encoding="utf-8")
+    with pytest.raises(ValueError, match="Unsupported file type"):
+        load_source_file(str(path))
+
+
+def test_load_empty_file_raises(tmp_path):
+    path = tmp_path / "empty.txt"
+    path.write_text("   \n\n  ", encoding="utf-8")
+    with pytest.raises(ValueError, match="No text could be extracted"):
+        load_source_file(str(path))
+
+
+def test_load_respects_max_chars(tmp_path):
+    path = tmp_path / "in.txt"
+    long_text = ("a" * 50 + "। ") * 10
+    path.write_text(long_text, encoding="utf-8")
+    segments = load_source_file(str(path), max_chars=100)
+    assert len(segments) > 1
+    assert all(len(s["source"]) <= 110 for s in segments)
+
+
+# ── the committed sample files (samples/sample_tibetan.*) ─────────────────
+
+SAMPLES_DIR = Path(__file__).parent.parent / "samples"
+
+
+@pytest.mark.parametrize("ext", ["txt", "docx", "pdf"])
+def test_sample_files_load_successfully(ext):
+    path = SAMPLES_DIR / f"sample_tibetan.{ext}"
+    segments = load_source_file(str(path))
+    assert len(segments) > 0
+    assert all(seg["target"] == "" for seg in segments)
+    combined = "".join(seg["source"] for seg in segments)
+    assert "སངས་རྒྱས" in combined  # "Buddha" appears in the refuge verse
+
+
+# ── parse_json ─────────────────────────────────────────────────────────────
+
+def test_parse_json_valid_list():
+    content = json.dumps([{"source": "src1", "target": "tgt1"}, {"source": "src2"}])
+    segments = parse_json(content)
+    assert segments == [
+        {"source": "src1", "target": "tgt1"},
+        {"source": "src2", "target": ""},
+    ]
+
+
+def test_parse_json_accepts_bytes():
+    content = json.dumps([{"source": "src1", "target": "tgt1"}]).encode("utf-8")
+    segments = parse_json(content)
+    assert segments == [{"source": "src1", "target": "tgt1"}]
+
+
+def test_parse_json_rejects_non_list():
+    with pytest.raises(ValueError, match="non-empty list"):
+        parse_json(json.dumps({"source": "a"}))
+
+
+def test_parse_json_rejects_empty_list():
+    with pytest.raises(ValueError, match="non-empty list"):
+        parse_json(json.dumps([]))
+
+
+def test_parse_json_rejects_missing_source():
+    with pytest.raises(ValueError, match="Item 0 is missing 'source'"):
+        parse_json(json.dumps([{"target": "only a target"}]))
+
+
+def test_parse_json_rejects_non_dict_item():
+    with pytest.raises(ValueError, match="Item 1 is missing 'source'"):
+        parse_json(json.dumps([{"source": "ok"}, "not a dict"]))
+
+
+# ── export_to_txt / export_to_docx / export_to_json ───────────────────────
+
+def test_export_to_txt_joins_nonempty_targets():
+    segments = [{"source": "s1", "target": "t1"}, {"source": "s2", "target": ""}, {"source": "s3", "target": "t3"}]
+    assert export_to_txt(segments, "target") == "t1\n\nt3\n"
+
+
+def test_export_to_txt_all_empty_returns_empty_string():
+    segments = [{"source": "s1", "target": ""}, {"source": "s2", "target": "  "}]
+    assert export_to_txt(segments, "target") == ""
+
+
+def test_export_to_txt_source_field():
+    segments = [{"source": "s1", "target": "t1"}, {"source": "s2", "target": "t2"}]
+    assert export_to_txt(segments, "source") == "s1\n\ns2\n"
+
+
+def test_export_to_docx_roundtrips_through_load(tmp_path):
+    docx = pytest.importorskip("docx")
+    segments = [{"source": "s1", "target": "First translation."}, {"source": "s2", "target": "Second translation."}]
+    data = export_to_docx(segments, "target")
+    assert isinstance(data, bytes) and len(data) > 0
+
+    out_path = tmp_path / "out.docx"
+    out_path.write_bytes(data)
+    doc = docx.Document(str(out_path))
+    texts = [p.text for p in doc.paragraphs if p.text.strip()]
+    assert texts == ["First translation.", "Second translation."]
+
+
+def test_export_to_docx_skips_empty_targets():
+    segments = [{"source": "s1", "target": ""}, {"source": "s2", "target": "kept"}]
+    data = export_to_docx(segments, "target")
+    docx = pytest.importorskip("docx")
+    import io
+    doc = docx.Document(io.BytesIO(data))
+    texts = [p.text for p in doc.paragraphs if p.text.strip()]
+    assert texts == ["kept"]
+
+
+def test_export_to_json_roundtrip():
+    segments = [{"source": "s1", "target": "t1"}, {"source": "s2", "target": ""}]
+    text = export_to_json(segments)
+    assert json.loads(text) == segments
+
+
+def test_export_to_json_preserves_unicode_without_escaping():
+    segments = [{"source": TIBETAN, "target": ""}]
+    text = export_to_json(segments)
+    assert TIBETAN in text  # ensure_ascii=False

tests/test_handlers.py

@@ -0,0 +1,380 @@
+import json
+import time
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+
+import handlers as h
+
+SAMPLES_DIR = Path(__file__).parent.parent / "samples"
+
+
+def _segments(*sources):
+    return [{"source": s, "target": ""} for s in sources]
+
+
+# ── state / pagination ──────────────────────────────────────────────────────
+
+def test_make_state_defaults():
+    state = h._make_state()
+    assert state == {"page": 0, "segments": [], "has_translation": False, "label": "output"}
+
+
+def test_save_page_edits_writes_current_page_slots():
+    state = h._make_state()
+    state["segments"] = _segments("a", "b", "c")
+    state["page"] = 0
+    sources = ["A", "B", "C"] + [""] * (h.MAX_SLOTS - 3)
+    targets = ["ta", "tb", "tc"] + [""] * (h.MAX_SLOTS - 3)
+    state = h._save_page_edits(state, sources, targets)
+    assert state["segments"] == [
+        {"source": "A", "target": "ta"},
+        {"source": "B", "target": "tb"},
+        {"source": "C", "target": "tc"},
+    ]
+
+
+def test_save_page_edits_respects_page_offset():
+    state = h._make_state()
+    state["segments"] = _segments(*[f"s{i}" for i in range(h.MAX_SLOTS + 2)])
+    state["page"] = 1
+    sources = ["edited0", "edited1"] + [""] * (h.MAX_SLOTS - 2)
+    targets = ["t0", "t1"] + [""] * (h.MAX_SLOTS - 2)
+    state = h._save_page_edits(state, sources, targets)
+    assert state["segments"][h.MAX_SLOTS]["source"] == "edited0"
+    assert state["segments"][h.MAX_SLOTS + 1]["source"] == "edited1"
+    assert state["segments"][0]["source"] == "s0"  # page 0 untouched
+
+
+def test_load_page_empty_state_hides_everything():
+    state = h._make_state()
+    result = h._load_page(state)
+    _, nav, prev, next_, *rest = result
+    assert nav["value"] == ""
+    assert prev["interactive"] is False
+    assert next_["interactive"] is False
+    groups = rest[:h.MAX_SLOTS]
+    assert all(g["visible"] is False for g in groups)
+
+
+def test_load_page_shows_correct_slot_count_and_nav_text():
+    state = h._make_state()
+    state["segments"] = _segments("a", "b", "c")
+    result = h._load_page(state)
+    _, nav, prev, next_, *rest = result
+    assert "All 3 segments" in nav["value"]
+    assert prev["interactive"] is False
+    assert next_["interactive"] is False
+    groups = rest[:h.MAX_SLOTS]
+    sources = rest[h.MAX_SLOTS:2 * h.MAX_SLOTS]
+    assert [g["visible"] for g in groups[:3]] == [True, True, True]
+    assert all(g["visible"] is False for g in groups[3:])
+    assert [s["value"] for s in sources[:3]] == ["a", "b", "c"]
+
+
+def test_load_page_pagination_across_multiple_pages():
+    total = h.MAX_SLOTS + 5
+    state = h._make_state()
+    state["segments"] = _segments(*[f"s{i}" for i in range(total)])
+    state["page"] = 0
+
+    result = h._load_page(state)
+    _, nav, prev, next_, *_rest = result
+    assert "Page 1 of 2" in nav["value"]
+    assert prev["interactive"] is False
+    assert next_["interactive"] is True
+
+    state["page"] = 1
+    result = h._load_page(state)
+    new_state, nav, prev, next_, *rest = result
+    assert "Page 2 of 2" in nav["value"]
+    assert prev["interactive"] is True
+    assert next_["interactive"] is False
+    groups = rest[:h.MAX_SLOTS]
+    assert [g["visible"] for g in groups[:5]] == [True] * 5
+    assert all(g["visible"] is False for g in groups[5:])
+
+
+def test_load_page_clamps_page_when_segments_shrank():
+    state = h._make_state()
+    state["segments"] = _segments("a")
+    state["page"] = 5  # stale page index from before segments were replaced
+    new_state, *_ = h._load_page(state)
+    assert new_state["page"] == 0
+
+
+def test_handle_prev_and_next_navigate_and_save(monkeypatch):
+    total = h.MAX_SLOTS + 3
+    state = h._make_state()
+    state["segments"] = _segments(*[f"s{i}" for i in range(total)])
+    state["page"] = 0
+    slot_values = [""] * h.MAX_SLOTS + [""] * h.MAX_SLOTS
+
+    result = h._handle_next(state, *slot_values)
+    new_state = result[0]
+    assert new_state["page"] == 1
+
+    result = h._handle_prev(new_state, *slot_values)
+    new_state = result[0]
+    assert new_state["page"] == 0
+
+
+def test_handle_next_does_not_advance_past_last_page():
+    state = h._make_state()
+    state["segments"] = _segments("a", "b")
+    state["page"] = 0
+    slot_values = [""] * h.MAX_SLOTS * 2
+    result = h._handle_next(state, *slot_values)
+    assert result[0]["page"] == 0
+
+
+def test_handle_prev_does_not_go_below_zero():
+    state = h._make_state()
+    state["segments"] = _segments("a", "b")
+    state["page"] = 0
+    slot_values = [""] * h.MAX_SLOTS * 2
+    result = h._handle_prev(state, *slot_values)
+    assert result[0]["page"] == 0
+
+
+# ── file loading ─────────────────────────────────────────────────────────
+
+def test_load_source_none_hides_editor():
+    state = h._make_state()
+    result = h._load_source(None, state)
+    assert result[-1]["visible"] is False
+
+
+def test_load_source_txt_populates_segments():
+    state = h._make_state()
+    path = str(SAMPLES_DIR / "sample_tibetan.txt")
+    result = h._load_source(path, state)
+    new_state = result[0]
+    assert len(new_state["segments"]) > 0
+    assert new_state["label"] == "sample_tibetan"
+    assert new_state["has_translation"] is False
+    assert result[-1]["visible"] is True
+
+
+def test_load_source_bad_file_hides_editor_and_does_not_raise(tmp_path):
+    bad_path = tmp_path / "bad.rtf"
+    bad_path.write_text("nope", encoding="utf-8")
+    state = h._make_state()
+    result = h._load_source(str(bad_path), state)
+    assert result[-1]["visible"] is False
+    assert state["segments"] == []
+
+
+def test_load_resume_json_merges_targets_by_position():
+    state = h._make_state()
+    state["segments"] = _segments("a", "b", "c")
+    resume_content = json.dumps([
+        {"source": "a", "target": "A"},
+        {"source": "b", "target": ""},
+        {"source": "c", "target": "C"},
+    ])
+    import tempfile
+    with tempfile.NamedTemporaryFile(suffix=".json", mode="w", delete=False) as f:
+        f.write(resume_content)
+        path = f.name
+
+    h._load_resume_json(path, state)
+    assert [s["target"] for s in state["segments"]] == ["A", "", "C"]
+    assert state["has_translation"] is True
+
+
+def test_load_resume_json_no_file_or_no_segments_is_noop():
+    state = h._make_state()
+    result = h._load_resume_json(None, state)
+    assert result[0] == state
+
+    state2 = h._make_state()
+    state2["segments"] = []
+    result = h._load_resume_json("irrelevant.json", state2)
+    assert result[0]["segments"] == []
+
+
+# ── downloads ────────────────────────────────────────────────────────────
+
+def test_make_downloads_writes_expected_files(tmp_path, monkeypatch):
+    monkeypatch.setattr(h.tempfile, "gettempdir", lambda: str(tmp_path))
+    segments = [{"source": "src1", "target": "tgt1"}]
+    paths = h._make_downloads(segments, "mylabel")
+    assert paths["txt"] and Path(paths["txt"]).read_text(encoding="utf-8") == "tgt1\n"
+    assert paths["docx"] and Path(paths["docx"]).exists()
+    assert json.loads(Path(paths["json"]).read_text(encoding="utf-8")) == segments
+    assert paths["source_txt"] and Path(paths["source_txt"]).name == "mylabel_source.txt"
+
+
+def test_make_downloads_omits_empty_content():
+    segments = [{"source": "", "target": ""}]
+    paths = h._make_downloads(segments, "mylabel")
+    assert paths["txt"] is None
+    assert paths["source_txt"] is None
+
+
+def test_handle_download_click_lists_available_formats(tmp_path, monkeypatch):
+    monkeypatch.setattr(h.tempfile, "gettempdir", lambda: str(tmp_path))
+    state = h._make_state()
+    state["segments"] = [{"source": "src", "target": "tgt"}]
+    # _handle_download_click saves current textbox contents before exporting, so the
+    # slot values passed in must reflect the segment we just seeded above.
+    sources = ["src"] + [""] * (h.MAX_SLOTS - 1)
+    targets = ["tgt"] + [""] * (h.MAX_SLOTS - 1)
+    slot_values = sources + targets
+    new_state, checklist, get_files_btn, download_zip = h._handle_download_click(state, *slot_values)
+    assert "Translation (TXT)" in checklist["choices"]
+    assert "Translation (DOCX)" in checklist["choices"]
+    assert "JSON (for resume)" in checklist["choices"]
+    assert "Source text (TXT)" in checklist["choices"]
+    assert get_files_btn["visible"] is True
+    assert download_zip["visible"] is False
+
+
+def test_handle_get_files_builds_zip_with_selected_formats(tmp_path, monkeypatch):
+    monkeypatch.setattr(h.tempfile, "gettempdir", lambda: str(tmp_path))
+    state = h._make_state()
+    state["segments"] = [{"source": "src", "target": "tgt"}]
+    state["label"] = "lbl"
+
+    zip_update, checklist_update, btn_update = h._handle_get_files(state, ["Translation (TXT)"])
+    assert zip_update["visible"] is True
+    zip_path = Path(zip_update["value"])
+    assert zip_path.exists()
+
+    import zipfile
+    with zipfile.ZipFile(zip_path) as zf:
+        assert zf.namelist() == ["lbl.txt"]
+
+
+def test_handle_get_files_no_selection_hides_download():
+    state = h._make_state()
+    state["segments"] = [{"source": "src", "target": "tgt"}]
+    zip_update, checklist_update, btn_update = h._handle_get_files(state, [])
+    assert zip_update["visible"] is False
+
+
+def test_handle_save_persists_edits_and_shows_status():
+    state = h._make_state()
+    state["segments"] = _segments("a")
+    slot_values = ["edited"] + [""] * (h.MAX_SLOTS - 1) + ["translated"] + [""] * (h.MAX_SLOTS - 1)
+    new_state, status = h._handle_save(state, *slot_values)
+    assert new_state["segments"][0] == {"source": "edited", "target": "translated"}
+    assert status["value"] == "Saved."
+
+
+# ── translation handlers ───────────────────���──────────────────────────────
+
+def test_translate_one_updates_state_and_returns_text():
+    state = h._make_state()
+    state["segments"] = _segments("source text")
+    state["page"] = 0
+    with patch.object(h, "_engine_translate_one", return_value="translated!") as mock_translate:
+        new_state, update = h._translate_one(state, 0, "source text", "api-key", "model-x")
+    assert update["value"] == "translated!"
+    assert new_state["segments"][0]["target"] == "translated!"
+    mock_translate.assert_called_once_with("source text", "api-key", "model-x")
+
+
+def test_translate_one_records_error_in_target():
+    state = h._make_state()
+    state["segments"] = _segments("source text")
+    with patch.object(h, "_engine_translate_one", side_effect=RuntimeError("network down")):
+        new_state, update = h._translate_one(state, 0, "source text", "api-key", "model-x")
+    assert "Translation error" in update["value"]
+    assert "network down" in new_state["segments"][0]["target"]
+
+
+def test_translate_one_out_of_range_slot_does_not_crash():
+    state = h._make_state()
+    state["segments"] = _segments("only one")
+    state["page"] = 0
+    with patch.object(h, "_engine_translate_one", return_value="x"):
+        new_state, update = h._translate_one(state, 5, "whatever", None, "model")
+    assert update["value"] == "x"
+    assert new_state["segments"] == _segments("only one")  # untouched, index out of range
+
+
+def test_translate_all_reports_completion_status():
+    state = h._make_state()
+    state["segments"] = _segments("a", "b")
+    # _translate_all saves current textbox contents before translating, so the slot
+    # values passed in must reflect the segments we just seeded above.
+    sources = ["a", "b"] + [""] * (h.MAX_SLOTS - 2)
+    targets = [""] * h.MAX_SLOTS
+    slot_values = sources + targets
+
+    def fake_translate_segments(segments, api_key, model, progress_callback=None, stop=None):
+        for seg in segments:
+            seg["target"] = seg["source"].upper()
+        return segments, []
+
+    with patch.object(h, "translate_segments", side_effect=fake_translate_segments), \
+         patch.object(h, "using_openrouter", return_value=True):
+        results = list(h._translate_all(state, "api-key", "model-x", *slot_values))
+
+    final = results[-1]
+    status = final[-1]
+    assert "Translated 2 segment(s) via OpenRouter." in status["value"]
+    final_state = final[0]
+    assert [s["target"] for s in final_state["segments"]] == ["A", "B"]
+
+
+def test_translate_all_reports_errors_in_status():
+    state = h._make_state()
+    state["segments"] = _segments("a", "b")
+    slot_values = [""] * h.MAX_SLOTS * 2
+
+    def fake_translate_segments(segments, api_key, model, progress_callback=None, stop=None):
+        return segments, ["Segment 1: boom"]
+
+    with patch.object(h, "translate_segments", side_effect=fake_translate_segments), \
+         patch.object(h, "using_openrouter", return_value=False):
+        results = list(h._translate_all(state, None, "model-x", *slot_values))
+
+    status = results[-1][-1]
+    assert "local CPU model" in status["value"]
+    assert "1 error(s)" in status["value"]
+
+
+def test_translate_all_cancel_sets_stop_event():
+    state = h._make_state()
+    state["segments"] = _segments(*[f"s{i}" for i in range(3)])
+    slot_values = [""] * h.MAX_SLOTS * 2
+
+    stop_seen = {}
+
+    def fake_translate_segments(segments, api_key, model, progress_callback=None, stop=None):
+        stop_seen["stop"] = stop
+        time.sleep(0.05)
+        return segments, []
+
+    with patch.object(h, "translate_segments", side_effect=fake_translate_segments):
+        gen = h._translate_all(state, "key", "model", *slot_values)
+        next(gen)  # drive it far enough to start the background thread
+        for _ in gen:
+            pass
+
+    assert stop_seen["stop"] is not None
+    assert not stop_seen["stop"].is_set()  # ran to completion, was never told to stop
+
+
+# ── prompt management ──────────────────────────────────────────────────────
+
+def test_read_save_reset_prompt_roundtrip(monkeypatch, tmp_path):
+    import engine.prompt as prompt_module
+    prompt_path = tmp_path / "translation_prompt.txt"
+    prompt_path.write_text("default", encoding="utf-8")
+    monkeypatch.setattr(prompt_module, "PROMPT_PATH", prompt_path)
+    monkeypatch.setattr(prompt_module, "_DEFAULT_PROMPT", "default")
+
+    assert h._read_prompt() == "default"
+
+    status = h._save_prompt("edited")
+    assert status["value"] == "Prompt saved."
+    assert h._read_prompt() == "edited"
+
+    box_update, status_update = h._reset_prompt()
+    assert box_update["value"] == "default"
+    assert status_update["value"] == "Prompt reset to default."

tests/test_local_backend.py

@@ -0,0 +1,136 @@
+"""Tests for engine/local_backend.py, stubbing out torch/transformers so this
+suite doesn't require installing the heavy real dependencies (torch is a
+multi-GB download and isn't needed to verify this module's own glue logic:
+prompt prefixing, device selection, and decode handling)."""
+
+import sys
+import types
+from unittest.mock import MagicMock
+
+import pytest
+
+
+@pytest.fixture
+def stubbed_torch_and_transformers(monkeypatch):
+    fake_torch = types.ModuleType("torch")
+    fake_torch.cuda = types.SimpleNamespace(is_available=lambda: False)
+
+    class _NoGrad:
+        def __enter__(self):
+            return None
+
+        def __exit__(self, *a):
+            return False
+
+    fake_torch.no_grad = _NoGrad
+    monkeypatch.setitem(sys.modules, "torch", fake_torch)
+
+    fake_transformers = types.ModuleType("transformers")
+    fake_transformers.AutoModelForSeq2SeqLM = MagicMock()
+    fake_transformers.AutoTokenizer = MagicMock()
+    monkeypatch.setitem(sys.modules, "transformers", fake_transformers)
+
+    return fake_torch, fake_transformers
+
+
+@pytest.fixture(autouse=True)
+def reset_model_cache(monkeypatch):
+    import engine.local_backend as lb
+    monkeypatch.setattr(lb, "_model", None)
+    monkeypatch.setattr(lb, "_tokenizer", None)
+    yield
+
+
+def _make_fake_model_and_tokenizer(decoded_outputs):
+    tokenizer = MagicMock()
+    encoded = MagicMock()
+    encoded.to.return_value = encoded
+    tokenizer.return_value = encoded
+    tokenizer.decode.side_effect = decoded_outputs
+
+    model = MagicMock()
+    model.to.return_value = model
+    model.generate.return_value = list(range(len(decoded_outputs)))  # dummy token id "rows"
+
+    return model, tokenizer
+
+
+def test_translate_batch_empty_list_short_circuits(stubbed_torch_and_transformers):
+    import engine.local_backend as lb
+    assert lb.translate_batch([]) == []
+
+
+def test_translate_batch_prefixes_and_decodes(stubbed_torch_and_transformers, monkeypatch):
+    import engine.local_backend as lb
+
+    model, tokenizer = _make_fake_model_and_tokenizer(["translation one", "translation two"])
+    monkeypatch.setattr(lb, "_load", lambda: (model, tokenizer))
+
+    result = lb.translate_batch(["first source", "second source"])
+
+    assert result == ["translation one", "translation two"]
+    called_texts = tokenizer.call_args[0][0]
+    assert called_texts == [
+        "translate Tibetan to English: first source",
+        "translate Tibetan to English: second source",
+    ]
+
+
+def test_translate_batch_uses_generation_settings_from_docstring(stubbed_torch_and_transformers, monkeypatch):
+    import engine.local_backend as lb
+
+    model, tokenizer = _make_fake_model_and_tokenizer(["out"])
+    monkeypatch.setattr(lb, "_load", lambda: (model, tokenizer))
+
+    lb.translate_batch(["text"])
+
+    _, kwargs = model.generate.call_args
+    assert kwargs["max_length"] == 300
+    assert kwargs["num_beams"] == 4
+    assert kwargs["early_stopping"] is True
+
+
+def test_translate_batch_uses_cpu_when_no_cuda(stubbed_torch_and_transformers, monkeypatch):
+    import engine.local_backend as lb
+
+    model, tokenizer = _make_fake_model_and_tokenizer(["out"])
+    monkeypatch.setattr(lb, "_load", lambda: (model, tokenizer))
+
+    lb.translate_batch(["text"])
+
+    model.to.assert_called_with("cpu")
+
+
+def test_translate_batch_uses_cuda_when_available(stubbed_torch_and_transformers, monkeypatch):
+    import engine.local_backend as lb
+
+    stubbed_torch_and_transformers[0].cuda.is_available = lambda: True
+    model, tokenizer = _make_fake_model_and_tokenizer(["out"])
+    monkeypatch.setattr(lb, "_load", lambda: (model, tokenizer))
+
+    lb.translate_batch(["text"])
+
+    model.to.assert_called_with("cuda")
+
+
+def test_load_caches_model_and_tokenizer_across_calls(stubbed_torch_and_transformers):
+    import engine.local_backend as lb
+
+    fake_model = MagicMock()
+    fake_tokenizer = MagicMock()
+
+    with pytest.MonkeyPatch.context() as mp:
+        mp.setattr(
+            sys.modules["transformers"], "AutoModelForSeq2SeqLM",
+            MagicMock(from_pretrained=MagicMock(return_value=fake_model)),
+        )
+        mp.setattr(
+            sys.modules["transformers"], "AutoTokenizer",
+            MagicMock(from_pretrained=MagicMock(return_value=fake_tokenizer)),
+        )
+        model1, tok1 = lb._load()
+        model2, tok2 = lb._load()
+
+    assert model1 is model2
+    assert tok1 is tok2
+    fake_model.eval.assert_called_once()

tests/test_openrouter_backend.py

@@ -0,0 +1,218 @@
+from unittest.mock import MagicMock, patch
+
+import pytest
+import requests
+
+from engine import openrouter_backend as ob
+
+
+# ── prompt building / response parsing (pure functions) ────────────────────
+
+def test_build_batch_prompt_numbers_lines_in_order():
+    prompt = ob._build_batch_prompt("TEMPLATE", ["first", "second", "third"])
+    assert "1. first" in prompt
+    assert "2. second" in prompt
+    assert "3. third" in prompt
+    assert prompt.startswith("TEMPLATE")
+
+
+def test_build_batch_prompt_includes_preceding_context_when_given():
+    prompt = ob._build_batch_prompt("TEMPLATE", ["text"], preceding=["prev1", "prev2"])
+    assert "prev1" in prompt
+    assert "prev2" in prompt
+    assert "translated immediately before" in prompt
+
+
+def test_build_batch_prompt_omits_context_block_when_no_preceding():
+    prompt = ob._build_batch_prompt("TEMPLATE", ["text"], preceding=None)
+    assert "translated immediately before" not in prompt
+
+
+def test_parse_batch_response_happy_path():
+    response = "1. hello\n2. world\n3. foo bar"
+    assert ob._parse_batch_response(response, 3) == ["hello", "world", "foo bar"]
+
+
+def test_parse_batch_response_wrong_count_returns_none():
+    response = "1. hello\n2. world"
+    assert ob._parse_batch_response(response, 3) is None
+
+
+def test_parse_batch_response_ignores_non_numbered_lines():
+    response = "Sure, here you go:\n1. hello\n2. world\nThanks!"
+    assert ob._parse_batch_response(response, 2) == ["hello", "world"]
+
+
+def test_parse_batch_response_empty_input():
+    assert ob._parse_batch_response("", 0) == []
+    assert ob._parse_batch_response("", 1) is None
+
+
+# ── model listing / curation ────────────────────────────────────────────────
+
+def _model(id_, modality="text->text", output_modalities=None):
+    return {
+        "id": id_,
+        "architecture": {
+            "modality": modality,
+            "output_modalities": output_modalities if output_modalities is not None else ["text"],
+        },
+    }
+
+
+def test_is_text_model_accepts_text_to_text():
+    assert ob._is_text_model(_model("a/a", modality="text->text"))
+
+
+def test_is_text_model_accepts_multimodal_input_text_output():
+    assert ob._is_text_model(_model("a/a", modality="text+image->text"))
+
+
+def test_is_text_model_rejects_image_output():
+    m = _model("a/a", modality="text->image", output_modalities=["image"])
+    assert not ob._is_text_model(m)
+
+
+def test_list_model_choices_puts_curated_first_then_rest_alphabetically():
+    fetched = [
+        _model("zzz/last"),
+        _model(ob.CURATED_MODELS[1]),
+        _model("aaa/first"),
+        _model(ob.CURATED_MODELS[0]),
+    ]
+    with patch.object(ob, "fetch_available_models", return_value=fetched):
+        choices = ob.list_model_choices()
+    assert choices == [ob.CURATED_MODELS[0], ob.CURATED_MODELS[1], "aaa/first", "zzz/last"]
+
+
+def test_list_model_choices_drops_curated_models_not_in_catalog():
+    fetched = [_model("aaa/first")]
+    with patch.object(ob, "fetch_available_models", return_value=fetched):
+        choices = ob.list_model_choices()
+    assert choices == ["aaa/first"]
+    for curated in ob.CURATED_MODELS:
+        assert curated not in choices
+
+
+def test_list_model_choices_filters_out_non_text_models():
+    fetched = [
+        _model(ob.CURATED_MODELS[0]),
+        _model("image/only", modality="text->image", output_modalities=["image"]),
+    ]
+    with patch.object(ob, "fetch_available_models", return_value=fetched):
+        choices = ob.list_model_choices()
+    assert "image/only" not in choices
+
+
+def test_list_model_choices_falls_back_to_curated_on_fetch_failure():
+    with patch.object(ob, "fetch_available_models", side_effect=requests.RequestException("network down")):
+        choices = ob.list_model_choices()
+    assert choices == list(ob.CURATED_MODELS)
+
+
+def test_fetch_available_models_hits_public_models_endpoint():
+    fake_resp = MagicMock()
+    fake_resp.json.return_value = {"data": [{"id": "a/a"}]}
+    with patch.object(ob.requests, "get", return_value=fake_resp) as mock_get:
+        result = ob.fetch_available_models(timeout=5)
+    mock_get.assert_called_once_with(f"{ob.BASE_URL}/models", timeout=5)
+    fake_resp.raise_for_status.assert_called_once()
+    assert result == [{"id": "a/a"}]
+
+
+# ── _call_openrouter (network layer) ────────────────────────────────────────
+
+def _http_response(status_code, json_body=None, text=""):
+    resp = MagicMock()
+    resp.status_code = status_code
+    resp.text = text
+    if json_body is not None:
+        resp.json.return_value = json_body
+    return resp
+
+
+def test_call_openrouter_success_returns_message_content():
+    ok = _http_response(200, {"choices": [{"message": {"content": "translated text"}}]})
+    with patch.object(ob.requests, "post", return_value=ok) as mock_post:
+        result = ob._call_openrouter("key123", "some/model", "prompt text")
+    assert result == "translated text"
+
+    _, kwargs = mock_post.call_args
+    assert kwargs["headers"]["Authorization"] == "Bearer key123"
+    assert kwargs["json"]["models"][0] == "some/model"
+    assert kwargs["json"]["messages"] == [{"role": "user", "content": "prompt text"}]
+
+
+def test_call_openrouter_includes_curated_models_as_serverside_fallback():
+    ok = _http_response(200, {"choices": [{"message": {"content": "x"}}]})
+    with patch.object(ob.requests, "post", return_value=ok) as mock_post:
+        ob._call_openrouter("key", ob.CURATED_MODELS[2], "prompt")
+    sent_models = mock_post.call_args.kwargs["json"]["models"]
+    assert sent_models[0] == ob.CURATED_MODELS[2]
+    assert set(sent_models) == set(ob.CURATED_MODELS)
+    assert len(sent_models) == len(ob.CURATED_MODELS)  # no duplicate of the primary model
+
+
+def test_call_openrouter_retries_on_retryable_status_then_succeeds():
+    bad = _http_response(429, text="rate limited")
+    good = _http_response(200, {"choices": [{"message": {"content": "ok"}}]})
+    with patch.object(ob.requests, "post", side_effect=[bad, good]), patch.object(ob.time, "sleep"):
+        result = ob._call_openrouter("key", "model", "prompt")
+    assert result == "ok"
+
+
+def test_call_openrouter_raises_immediately_on_non_retryable_status():
+    unauthorized = _http_response(401, text="invalid api key")
+    with patch.object(ob.requests, "post", return_value=unauthorized) as mock_post:
+        with pytest.raises(RuntimeError, match="401"):
+            ob._call_openrouter("bad-key", "model", "prompt")
+    assert mock_post.call_count == 1
+
+
+def test_call_openrouter_exhausts_retries_and_raises_last_error():
+    bad = _http_response(503, text="unavailable")
+    with patch.object(ob.requests, "post", return_value=bad), patch.object(ob.time, "sleep"):
+        with pytest.raises(RuntimeError, match="503"):
+            ob._call_openrouter("key", "model", "prompt")
+
+
+def test_call_openrouter_retries_on_network_exception():
+    good = _http_response(200, {"choices": [{"message": {"content": "recovered"}}]})
+    with patch.object(
+        ob.requests, "post", side_effect=[requests.ConnectionError("boom"), good]
+    ), patch.object(ob.time, "sleep"):
+        result = ob._call_openrouter("key", "model", "prompt")
+    assert result == "recovered"
+
+
+# ── translate_one / translate_batch ─────────────────────────────────────────
+
+def test_translate_one_strips_whitespace_from_response():
+    with patch.object(ob, "_call_openrouter", return_value="  translated  \n"):
+        result = ob.translate_one("source text", "key", "model", "template")
+    assert result == "translated"
+
+
+def test_translate_batch_empty_texts_short_circuits_without_network():
+    with patch.object(ob, "_call_openrouter") as mock_call:
+        result = ob.translate_batch([], "key", "model", "template")
+    assert result == []
+    mock_call.assert_not_called()
+
+
+def test_translate_batch_happy_path():
+    with patch.object(ob, "_call_openrouter", return_value="1. one\n2. two"):
+        result = ob.translate_batch(["a", "b"], "key", "model", "template")
+    assert result == ["one", "two"]
+
+
+def test_translate_batch_returns_none_on_parse_mismatch():
+    with patch.object(ob, "_call_openrouter", return_value="1. only one line"):
+        result = ob.translate_batch(["a", "b"], "key", "model", "template")
+    assert result is None
+
+
+def test_translate_batch_returns_none_on_network_error():
+    with patch.object(ob, "_call_openrouter", side_effect=RuntimeError("boom")):
+        result = ob.translate_batch(["a", "b"], "key", "model", "template")
+    assert result is None

tests/test_prompt.py

@@ -0,0 +1,44 @@
+import importlib
+
+import engine.prompt as prompt_module
+
+
+def _reload_with_prompt_path(monkeypatch, tmp_path, initial_text):
+    prompt_path = tmp_path / "translation_prompt.txt"
+    prompt_path.write_text(initial_text, encoding="utf-8")
+    monkeypatch.setattr(prompt_module, "PROMPT_PATH", prompt_path)
+    monkeypatch.setattr(prompt_module, "_DEFAULT_PROMPT", initial_text)
+    return prompt_path
+
+
+def test_read_prompt_returns_file_contents(monkeypatch, tmp_path):
+    _reload_with_prompt_path(monkeypatch, tmp_path, "default prompt text")
+    assert prompt_module.read_prompt() == "default prompt text"
+
+
+def test_save_prompt_persists_to_file(monkeypatch, tmp_path):
+    path = _reload_with_prompt_path(monkeypatch, tmp_path, "default prompt text")
+    prompt_module.save_prompt("edited prompt text")
+    assert path.read_text(encoding="utf-8") == "edited prompt text"
+    assert prompt_module.read_prompt() == "edited prompt text"
+
+
+def test_reset_prompt_restores_default_and_writes_file(monkeypatch, tmp_path):
+    path = _reload_with_prompt_path(monkeypatch, tmp_path, "default prompt text")
+    prompt_module.save_prompt("edited prompt text")
+    result = prompt_module.reset_prompt()
+    assert result == "default prompt text"
+    assert path.read_text(encoding="utf-8") == "default prompt text"
+
+
+def test_read_prompt_falls_back_to_default_when_file_missing(monkeypatch, tmp_path):
+    path = _reload_with_prompt_path(monkeypatch, tmp_path, "default prompt text")
+    path.unlink()
+    assert prompt_module.read_prompt() == "default prompt text"
+
+
+def test_default_prompt_file_exists_and_is_nonempty():
+    # sanity check on the real shipped translation_prompt.txt, independent of monkeypatching above
+    importlib.reload(prompt_module)
+    assert prompt_module.PROMPT_PATH.exists()
+    assert len(prompt_module.read_prompt().strip()) > 0

tests/test_translate.py

@@ -0,0 +1,181 @@
+import threading
+from unittest.mock import patch
+
+import pytest
+
+from engine import translate as tr
+
+
+# ── _resolve_key / using_openrouter ─────────────────────────────────────────
+
+def test_resolve_key_prefers_explicit_argument(monkeypatch):
+    monkeypatch.setenv("OPENROUTER_API_KEY", "env-key")
+    assert tr._resolve_key("explicit-key") == "explicit-key"
+
+
+def test_resolve_key_falls_back_to_env_var(monkeypatch):
+    monkeypatch.setenv("OPENROUTER_API_KEY", "env-key")
+    assert tr._resolve_key(None) == "env-key"
+    assert tr._resolve_key("") == "env-key"
+    assert tr._resolve_key("   ") == "env-key"
+
+
+def test_resolve_key_empty_when_neither_set(monkeypatch):
+    monkeypatch.delenv("OPENROUTER_API_KEY", raising=False)
+    assert tr._resolve_key(None) == ""
+
+
+def test_resolve_key_strips_whitespace(monkeypatch):
+    monkeypatch.delenv("OPENROUTER_API_KEY", raising=False)
+    assert tr._resolve_key("  key-with-spaces  ") == "key-with-spaces"
+
+
+def test_using_openrouter_true_and_false(monkeypatch):
+    monkeypatch.delenv("OPENROUTER_API_KEY", raising=False)
+    assert tr.using_openrouter("some-key") is True
+    assert tr.using_openrouter(None) is False
+    assert tr.using_openrouter("") is False
+
+
+# ── translate_one dispatch ───────────────────────────────────────────────────
+
+def test_translate_one_uses_openrouter_when_key_present(monkeypatch):
+    monkeypatch.delenv("OPENROUTER_API_KEY", raising=False)
+    with patch("engine.translate.openrouter_backend.translate_one", return_value="translated") as mock_or, \
+         patch("engine.translate.local_backend.translate_batch") as mock_local:
+        result = tr.translate_one("source", "api-key", "model-x")
+    assert result == "translated"
+    mock_or.assert_called_once()
+    mock_local.assert_not_called()
+
+
+def test_translate_one_uses_local_backend_when_no_key(monkeypatch):
+    monkeypatch.delenv("OPENROUTER_API_KEY", raising=False)
+    with patch("engine.translate.openrouter_backend.translate_one") as mock_or, \
+         patch("engine.translate.local_backend.translate_batch", return_value=["local translation"]) as mock_local:
+        result = tr.translate_one("source", None, "model-x")
+    assert result == "local translation"
+    mock_or.assert_not_called()
+    mock_local.assert_called_once_with(["source"])
+
+
+# ── translate_segments ───────────────────────────────────────────────────────
+
+def _segments(*sources):
+    return [{"source": s, "target": ""} for s in sources]
+
+
+def test_translate_segments_skips_already_translated(monkeypatch):
+    monkeypatch.delenv("OPENROUTER_API_KEY", raising=False)
+    segments = [{"source": "a", "target": ""}, {"source": "b", "target": "already done"}]
+    with patch("engine.translate.local_backend.translate_batch", return_value=["A"]) as mock_local:
+        result, errors = tr.translate_segments(segments, None, "model")
+    assert result[0]["target"] == "A"
+    assert result[1]["target"] == "already done"
+    assert errors == []
+    mock_local.assert_called_once_with(["a"])
+
+
+def test_translate_segments_skips_empty_source():
+    segments = [{"source": "", "target": ""}, {"source": "  ", "target": ""}]
+    with patch("engine.translate.local_backend.translate_batch") as mock_local:
+        result, errors = tr.translate_segments(segments, None, "model")
+    mock_local.assert_not_called()
+    assert errors == []
+
+
+def test_translate_segments_local_backend_path(monkeypatch):
+    monkeypatch.delenv("OPENROUTER_API_KEY", raising=False)
+    segments = _segments("a", "b")
+    with patch("engine.translate.local_backend.translate_batch", return_value=["A", "B"]):
+        result, errors = tr.translate_segments(segments, None, "model")
+    assert [s["target"] for s in result] == ["A", "B"]
+    assert errors == []
+
+
+def test_translate_segments_local_backend_error_recorded(monkeypatch):
+    monkeypatch.delenv("OPENROUTER_API_KEY", raising=False)
+    segments = _segments("a", "b")
+    with patch("engine.translate.local_backend.translate_batch", side_effect=RuntimeError("model crashed")):
+        result, errors = tr.translate_segments(segments, None, "model")
+    assert len(errors) == 2
+    assert "model crashed" in errors[0]
+    assert all(s["target"] == "" for s in result)
+
+
+def test_translate_segments_openrouter_batch_success():
+    segments = _segments("a", "b")
+    with patch("engine.translate.openrouter_backend.translate_batch", return_value=["A", "B"]) as mock_batch:
+        result, errors = tr.translate_segments(segments, "key", "model")
+    assert [s["target"] for s in result] == ["A", "B"]
+    assert errors == []
+    mock_batch.assert_called_once()
+
+
+def test_translate_segments_openrouter_batch_falls_back_to_per_segment():
+    segments = _segments("a", "b")
+    with patch("engine.translate.openrouter_backend.translate_batch", return_value=None), \
+         patch("engine.translate.openrouter_backend.translate_one", side_effect=["A", "B"]) as mock_one:
+        result, errors = tr.translate_segments(segments, "key", "model")
+    assert [s["target"] for s in result] == ["A", "B"]
+    assert errors == []
+    assert mock_one.call_count == 2
+
+
+def test_translate_segments_per_segment_fallback_records_errors_and_continues():
+    segments = _segments("a", "b")
+    with patch("engine.translate.openrouter_backend.translate_batch", return_value=None), \
+         patch("engine.translate.openrouter_backend.translate_one", side_effect=[RuntimeError("bad"), "B"]):
+        result, errors = tr.translate_segments(segments, "key", "model")
+    assert result[0]["target"] == ""  # failed segment left untouched
+    assert result[1]["target"] == "B"
+    assert len(errors) == 1
+    assert "Segment 1" in errors[0]
+
+
+def test_translate_segments_respects_stop_event_between_batches():
+    stop = threading.Event()
+    segments = _segments(*[f"seg{i}" for i in range(60)])  # 60 > _BATCH_SIZE(25), needs 3 batches
+
+    call_count = {"n": 0}
+
+    def fake_batch(texts, *a, **kw):
+        call_count["n"] += 1
+        if call_count["n"] == 1:
+            stop.set()
+        return [t.upper() for t in texts]
+
+    with patch("engine.translate.openrouter_backend.translate_batch", side_effect=fake_batch):
+        result, errors = tr.translate_segments(segments, "key", "model", stop=stop)
+
+    assert call_count["n"] == 1  # stopped before the second batch
+    assert result[0]["target"] == "SEG0"
+    assert result[59]["target"] == ""
+
+
+def test_translate_segments_progress_callback_invoked_per_batch():
+    segments = _segments(*[f"seg{i}" for i in range(30)])
+    progress_calls = []
+
+    with patch("engine.translate.openrouter_backend.translate_batch", side_effect=lambda texts, *a, **kw: texts):
+        tr.translate_segments(
+            segments, "key", "model",
+            progress_callback=lambda i, total: progress_calls.append((i, total)),
+        )
+
+    assert progress_calls == [(0, 30), (25, 30)]
+
+
+def test_translate_segments_passes_recent_translations_as_preceding_context():
+    segments = _segments(*[f"seg{i}" for i in range(30)])
+    seen_preceding = []
+
+    def fake_batch(texts, api_key, model, template, preceding=None):
+        seen_preceding.append(preceding)
+        return texts
+
+    with patch("engine.translate.openrouter_backend.translate_batch", side_effect=fake_batch):
+        tr.translate_segments(segments, "key", "model")
+
+    assert seen_preceding[0] is None  # nothing translated yet for the first batch
+    assert seen_preceding[1] == ["seg22", "seg23", "seg24"]  # last 3 of the first batch