mvp

.gitattributes

@@ -0,0 +1,35 @@
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,23 @@
+# Python bytecode / caches
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+
+# Gradio runtime artifacts (local cache, dev cert, flagged data, cached examples)
+.gradio/
+flagged/
+gradio_cached_examples/
+
+# Secrets / local env (MODAL_KEY, MODAL_SECRET, MODAL_*_URL live in Space secrets)
+.env
+.env.*
+
+# Virtual envs
+.venv/
+venv/
+
+# Editor / OS cruft
+.idea/
+.vscode/
+.DS_Store

app.py

@@ -0,0 +1,413 @@
+#!/usr/bin/env python3
+"""Dictation Trainer — Gradio Space (specs/gradio.md).
+
+A thin, mobile-first wrapper over three Modal endpoints. No models run here:
+every inference is an HTTP call out to Modal.
+
+  Generate: word list + level --LLM--> German dictation --TTS--> audio
+  Check:    photo of handwriting --OCR(blind)--> text --grade--> diff + score
+
+Run locally from this directory (the Space root):
+  MODAL_LLM_URL=... MODAL_TTS_URL=... MODAL_OCR_URL=... uv run python app.py
+"""
+
+import json
+import os
+import tempfile
+import time
+
+import gradio as gr
+from loguru import logger
+
+# Flat imports: this file is the Space entrypoint, run with space/ as the root.
+from diff_html import render_report_html
+from ocr.grading import grade
+from ocr.transcribe import transcribe_image
+from openai_client import make_client
+from prompts import (
+    DICTATION_SYSTEM_PROMPT,
+    build_user_prompt,
+    clean_dictation,
+    parse_word_list,
+)
+from wizard import nav
+
+LLM_MODEL = "LiquidAI/LFM2.5-8B-A1B-GGUF"
+# Higgs ignores the model field today, but the OpenAI SDK requires one; keep it
+# descriptive in case the server starts validating it.
+TTS_MODEL = "bosonai/higgs-audio-v3-tts-4b"
+TTS_VOICE = "alba"
+# Sampling fixed per spec §6 — deterministic, repeatable dictations. top_k and
+# repeat_penalty aren't OpenAI-standard params, so they ride in extra_body.
+LLM_SAMPLING = {
+    "temperature": 0.1,
+    "top_p": 0.1,
+    "top_k": 50,
+    "repeat_penalty": 1.05,
+}
+# LFM2.5 is a reasoning model: it emits a chain-of-thought into `reasoning_content`
+# BEFORE the answer goes into `content`. The token budget must cover BOTH, or the
+# reasoning consumes it all and `content` comes back empty (finish_reason=length).
+# The verbose system prompt lengthens the reasoning, so keep this well above the
+# ~900 tokens of CoT we observed. See space/debug_llm.py.
+LLM_MAX_TOKENS = 2048
+LANG = "de"
+
+COLD_START_HINT = "First call after idle can take ~30-60s while backend warms up."
+
+# Calm, modern theme: indigo/violet accents on slate neutrals, a soft gradient
+# page, white cards with gentle shadows, roomy radius + spacing. Most of the look
+# lives here (theme variables are version-stable); CSS below only does the things
+# themes can't (phone framing, gradient title, status pill).
+THEME = gr.themes.Soft(
+    primary_hue=gr.themes.colors.indigo,
+    secondary_hue=gr.themes.colors.sky,
+    neutral_hue=gr.themes.colors.slate,
+    font=[gr.themes.GoogleFont("Inter"), "ui-sans-serif", "system-ui", "sans-serif"],
+    radius_size=gr.themes.sizes.radius_lg,
+    spacing_size=gr.themes.sizes.spacing_lg,
+    text_size=gr.themes.sizes.text_md,
+).set(
+    body_background_fill="linear-gradient(160deg, #eef2fb 0%, #e9ecf7 45%, #ece9f7 100%)",
+    body_background_fill_dark="linear-gradient(160deg, #0f1422 0%, #141b2d 100%)",
+    body_text_color="#1e293b",
+    body_text_color_subdued="#64748b",
+    block_background_fill="#ffffff",
+    block_background_fill_dark="#1a2234",
+    block_border_width="0px",
+    block_radius="18px",
+    block_shadow="0 6px 24px rgba(30, 41, 59, 0.08)",
+    block_shadow_dark="0 6px 24px rgba(0, 0, 0, 0.40)",
+    block_padding="20px",
+    layout_gap="14px",
+    input_background_fill="#f8fafc",
+    input_background_fill_dark="#0f1626",
+    input_radius="12px",
+    button_large_radius="12px",
+    button_large_padding="11px 18px",
+    button_primary_background_fill="linear-gradient(135deg, #6366f1 0%, #8b5cf6 100%)",
+    button_primary_background_fill_hover="linear-gradient(135deg, #4f46e5 0%, #7c3aed 100%)",
+    button_primary_background_fill_dark="linear-gradient(135deg, #6366f1 0%, #8b5cf6 100%)",
+    button_primary_text_color="#ffffff",
+    button_primary_shadow="0 4px 14px rgba(99, 102, 241, 0.35)",
+    button_primary_shadow_hover="0 6px 18px rgba(99, 102, 241, 0.45)",
+)
+
+# Portrait-phone framing + the bits the theme can't express: a narrow centered
+# column, a gradient app title, and the centered status (spinner) pill.
+MOBILE_CSS = """
+.gradio-container {
+    max-width: 480px !important;
+    margin: 0 auto !important;
+    padding: 12px 14px 28px !important;
+}
+.gradio-container h1 {
+    font-size: 1.6rem;
+    font-weight: 700;
+    text-align: center;
+    margin: 10px 0 2px;
+    background: linear-gradient(135deg, #6366f1, #8b5cf6);
+    -webkit-background-clip: text;
+    background-clip: text;
+    -webkit-text-fill-color: transparent;
+}
+/* Step title: transparent (no clipped grey strip), larger, and padded so the
+   card's rounded corner never crops the leading "1 ·". */
+.panel-title {
+    background: transparent !important;
+    box-shadow: none !important;
+    border: none !important;
+    padding: 6px 18px 2px !important;
+}
+.panel-title h3 {
+    font-size: 1.35rem !important;
+    font-weight: 700 !important;
+    color: #4f46e5 !important;
+    margin: 0 !important;
+    line-height: 1.3;
+}
+.status {
+    text-align: center;
+    font-weight: 600;
+    opacity: 0.9;
+}
+.status .fa-spinner {
+    margin-right: 6px;
+}
+"""
+
+# FontAwesome (CDN) for the animated status spinner (fa-spinner + fa-spin). Loaded
+# into <head> at launch; the icon itself is rendered as raw HTML in the status
+# fields (see _busy), which is why those Markdowns set sanitize_html=False.
+FA_HEAD = (
+    '<link rel="stylesheet" '
+    'href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.2/css/all.min.css">'
+)
+SPINNER = '<i class="fa-solid fa-spinner fa-spin"></i>'
+
+
+def _require_env(name: str) -> str:
+    val = os.environ.get(name)
+    if not val:
+        raise gr.Error(f"{name} is not configured (set it in the Space secrets).")
+    return val
+
+
+def _tts_base_url() -> str:
+    """MODAL_TTS_URL may be the server root or the full speech path; reduce it to
+    the server root so the client appends /v1/audio/speech itself."""
+    url = _require_env("MODAL_TTS_URL").rstrip("/")
+    for suffix in ("/v1/audio/speech", "/audio/speech"):
+        if url.endswith(suffix):
+            return url[: -len(suffix)]
+    return url
+
+
+def call_llm(words: list[str], level: str) -> str:
+    """Word list + CEFR level -> one German dictation paragraph (cleaned)."""
+    client = make_client(_require_env("MODAL_LLM_URL"))
+    completion = client.chat.completions.create(
+        model=LLM_MODEL,
+        messages=[
+            {"role": "system", "content": DICTATION_SYSTEM_PROMPT},
+            {"role": "user", "content": build_user_prompt(words, level)},
+        ],
+        max_tokens=LLM_MAX_TOKENS,
+        extra_body=LLM_SAMPLING,
+    )
+    data = completion.model_dump()
+    choice = data.get("choices", [{}])[0]
+    content = (choice.get("message") or {}).get("content")
+    text = clean_dictation(content)
+    if not text:
+        # Evidence at the LLM boundary: see exactly what came back when empty.
+        logger.error(
+            "Empty dictation from LLM. finish_reason={} raw_content={!r}\nfull response: {}",
+            choice.get("finish_reason"),
+            content,
+            json.dumps(data, ensure_ascii=False)[:2000],
+        )
+    return text
+
+
+def call_tts(text: str) -> str:
+    """Synthesize the dictation; return a temp audio file path. Suffix follows
+    the response Content-Type so gr.Audio plays it without transcoding."""
+    client = make_client(_tts_base_url())
+    response = client.audio.speech.create(model=TTS_MODEL, voice=TTS_VOICE, input=text)
+    audio = response.read()
+    content_type = response.response.headers.get("content-type", "")
+    suffix = ".mp3" if "mpeg" in content_type else ".wav"
+    with tempfile.NamedTemporaryFile(suffix=suffix, delete=False) as f:
+        f.write(audio)
+        return f.name
+
+
+# ---- Step handlers ---------------------------------------------------------
+#
+# CTA handlers do their work, then append nav(...) so the wizard advances only on
+# success; raising gr.Error leaves every output (including the views) untouched,
+# so the user stays on the current step to fix the problem.
+
+
+def start(words_raw: str, level: str, state: dict):
+    """Input → Listen: generate the dictation text + audio."""
+    words = parse_word_list(words_raw)
+    if not words:
+        raise gr.Error("Enter at least one word to practice.")
+
+    text = call_llm(words, level)
+    if not text:
+        logger.error("LLM returned an empty dictation ({} words, {})", len(words), level)
+        raise gr.Error("The model returned an empty dictation. Please try again.")
+    logger.info("Generated dictation ({} words, {}):\n{}", len(words), level, text)
+    state = {"diktat": text, "created_at": time.time()}
+
+    try:
+        audio_path = call_tts(text)
+    except Exception as e:  # never lose the text because synthesis failed (spec §4)
+        gr.Warning(f"Audio synthesis failed ({e}). Text saved — open 'Show text'.")
+        audio_path = None
+
+    return audio_path, text, state, *nav("listen")
+
+
+def check(image_path: str, state: dict):
+    """Upload → Results: transcribe the photo (blind) and grade it."""
+    if not state or not state.get("diktat"):
+        raise gr.Error("Generate a dictation first.")
+    if not image_path:
+        raise gr.Error("Upload a photo of your handwriting first.")
+
+    ocr_client = make_client(_require_env("MODAL_OCR_URL"))
+    transcription = transcribe_image(image_path, ocr_client)
+    logger.info("OCR transcription:\n{}", transcription)
+    report = grade(state["diktat"], transcription, LANG)
+    return transcription, render_report_html(report), *nav("results")
+
+
+def restart():
+    """Results → Input: clear everything and start a fresh dictation."""
+    fresh = {"diktat": "", "created_at": 0}
+    # order matches the `outputs` list on the Start-over button below.
+    return "", None, "", None, "", "", fresh, *nav("input")
+
+
+# Inline progress: the CTA's real outputs all live on the next (hidden) view, so
+# Gradio's spinner would paint where the user can't see it. Instead each CTA runs
+# as show-status -> work -> hide-status; the hide step uses .then so it fires even
+# when the work raises (no spinner left stuck on screen).
+
+
+def _busy(message: str):
+    return gr.update(value=f"{SPINNER} {message}", visible=True)
+
+
+def _idle():
+    return gr.update(visible=False)
+
+
+def _begin(message: str):
+    """Show the spinner and disable the CTA so it can't be re-fired mid-call."""
+    return _busy(message), gr.update(interactive=False)
+
+
+def _end():
+    """Hide the spinner and re-enable the CTA on success (.then path)."""
+    return _idle(), gr.update(interactive=True)
+
+
+def _recover(*_):
+    """Same cleanup for the failure path. A raised gr.Error aborts the chained
+    .then, so re-enabling has to be wired via .failure (which passes the
+    exception as an arg — ignored here). Without this, a validation error like
+    'no photo uploaded' would leave the button stuck disabled."""
+    return _idle(), gr.update(interactive=True)
+
+
+def goto(target: str):
+    """Switch to a view and clear transient state (both status spinners hidden,
+    both CTAs re-enabled). Navigating away during a wait shouldn't leave a stale
+    spinner or a disabled button behind on the view you left. Return order matches
+    the NAV_OUTPUTS list wired in build_ui."""
+    return (
+        *nav(target),
+        gr.update(visible=False),     # input_status
+        gr.update(visible=False),     # upload_status
+        gr.update(interactive=True),  # start_btn
+        gr.update(interactive=True),  # check_btn
+    )
+
+
+# ---- UI --------------------------------------------------------------------
+
+
+def build_ui() -> gr.Blocks:
+    with gr.Blocks(title="Dictation Trainer") as demo:
+        # localStorage-backed: survives a tab reload while the learner writes (spec §3).
+        state = gr.BrowserState({"diktat": "", "created_at": 0})
+
+        gr.Markdown("# ✍️ German Dictation Trainer")
+
+        # Four stacked views; nav() keeps exactly one visible. Order must match
+        # wizard.VIEWS.
+        with gr.Group(visible=True) as view_input:
+            gr.Markdown("### 1 · Words to practice", elem_classes="panel-title")
+            words_in = gr.Textbox(
+                label="Words to practice",
+                placeholder="Comma- or newline-separated, e.g. angeblich, ablehnen, Apfel",
+                lines=4,
+            )
+            level_in = gr.Dropdown(["A1", "A2", "B1", "B2"], value="A2", label="Level")
+            start_btn = gr.Button("Start", variant="primary")
+            input_status = gr.Markdown(visible=False, sanitize_html=False, elem_classes="status")
+
+        with gr.Group(visible=False) as view_listen:
+            gr.Markdown("### 2 · Listen", elem_classes="panel-title")
+            audio_out = gr.Audio(
+                type="filepath", interactive=False, label="Dictation audio"
+            )
+            gr.Markdown("🎧 Listen and write it down on paper, then click **Finished**.")
+            with gr.Accordion("Show text (debug)", open=False):
+                text_out = gr.Textbox(label="Dictation text", interactive=False, lines=4)
+            with gr.Row():
+                listen_back_btn = gr.Button("Back")
+                finished_btn = gr.Button("Finished", variant="primary")
+
+        with gr.Group(visible=False) as view_upload:
+            gr.Markdown("### 3 · Upload your handwriting", elem_classes="panel-title")
+            image_in = gr.Image(
+                type="filepath",
+                sources=["upload", "webcam"],
+                label="Photo of your handwriting",
+            )
+            with gr.Row():
+                upload_back_btn = gr.Button("Back")
+                check_btn = gr.Button("Check", variant="primary")
+            upload_status = gr.Markdown(visible=False, sanitize_html=False, elem_classes="status")
+
+        with gr.Group(visible=False) as view_results:
+            gr.Markdown("### 4 · Results", elem_classes="panel-title")
+            recognized_out = gr.Textbox(
+                label="Recognized text (OCR)", interactive=False, lines=4
+            )
+            diff_out = gr.HTML(label="Feedback")
+            with gr.Row():
+                results_back_btn = gr.Button("Back")
+                restart_btn = gr.Button("Start over", variant="primary")
+
+        views = [view_input, view_listen, view_upload, view_results]
+
+        # CTA handlers: disable the button + show status, do the work (advance, or
+        # raise gr.Error and stay). On success .then clears + re-enables; on error
+        # .failure does the same (the raise aborts .then), so the button is never
+        # left stuck disabled.
+        start_work = start_btn.click(
+            lambda: _begin(f"Generating dictation… {COLD_START_HINT}"),
+            outputs=[input_status, start_btn],
+            show_progress="hidden",
+        ).then(
+            start,
+            inputs=[words_in, level_in, state],
+            outputs=[audio_out, text_out, state, *views],
+        )
+        start_work.then(_end, outputs=[input_status, start_btn], show_progress="hidden")
+        start_work.failure(_recover, outputs=[input_status, start_btn], show_progress="hidden")
+
+        check_work = check_btn.click(
+            lambda: _begin(f"Reading your handwriting… {COLD_START_HINT}"),
+            outputs=[upload_status, check_btn],
+            show_progress="hidden",
+        ).then(
+            check,
+            inputs=[image_in, state],
+            outputs=[recognized_out, diff_out, *views],
+        )
+        check_work.then(_end, outputs=[upload_status, check_btn], show_progress="hidden")
+        check_work.failure(_recover, outputs=[upload_status, check_btn], show_progress="hidden")
+        restart_btn.click(
+            restart,
+            outputs=[words_in, audio_out, text_out, image_in, recognized_out, diff_out, state, *views],
+        )
+
+        # Navigation (Finished + Back buttons): switch view AND clear any leftover
+        # spinner / disabled CTA from an action on the view being left. `cancels`
+        # aborts an in-flight Start/Check so a call the user navigated away from
+        # can't complete and yank them forward (its outputs are discarded).
+        nav_outputs = [*views, input_status, upload_status, start_btn, check_btn]
+        in_flight = [start_work, check_work]
+        finished_btn.click(lambda: goto("upload"), outputs=nav_outputs, cancels=in_flight)
+        listen_back_btn.click(lambda: goto("input"), outputs=nav_outputs, cancels=in_flight)
+        upload_back_btn.click(lambda: goto("listen"), outputs=nav_outputs, cancels=in_flight)
+        results_back_btn.click(lambda: goto("upload"), outputs=nav_outputs, cancels=in_flight)
+
+    return demo
+
+
+if __name__ == "__main__":
+    # On HF Spaces (SPACE_ID set) the runtime serves the app — don't request a
+    # share tunnel there; locally, share=True gives a link usable from a phone.
+    # theme, css and head all live on launch() in Gradio 6 (moved off Blocks).
+    build_ui().launch(
+        theme=THEME, css=MOBILE_CSS, head=FA_HEAD, share="SPACE_ID" not in os.environ
+    )

debug_llm.py

@@ -0,0 +1,82 @@
+#!/usr/bin/env python3
+"""Controlled experiment to find why the Space's dictation comes back empty.
+
+Sends several payload variants to MODAL_LLM_URL, changing ONE variable at a
+time vs. the known-good pipeline_tts.py recipe, and prints the raw response so
+we can see which variable empties the output and where it disappears.
+
+  MODAL_LLM_URL=https://<ws>--lfm25-8b-a1b-serve.modal.run uv run python debug_llm.py
+"""
+
+import json
+import os
+import sys
+
+import requests
+
+URL = os.environ.get("MODAL_LLM_URL")
+if not URL:
+    sys.exit("Set MODAL_LLM_URL first.")
+ENDPOINT = f"{URL.rstrip('/')}/v1/chat/completions"
+MODEL = "LiquidAI/LFM2.5-8B-A1B-GGUF"
+
+from prompts import DICTATION_SYSTEM_PROMPT, build_user_prompt  # noqa: E402
+
+WORDS = ["angeblich", "ablehnen", "Apfel", "Birne", "mitkriegen"]
+LEVEL = "B1"
+
+PIPELINE_SAMPLING = {"temperature": 0.2, "top_k": 80, "repeat_penalty": 1.05}
+APP_SAMPLING = {"temperature": 0.1, "top_p": 0.1, "top_k": 50, "repeat_penalty": 1.05}
+USER_MSG = {"role": "user", "content": build_user_prompt(WORDS, LEVEL)}
+SYSTEM_MSG = {"role": "system", "content": DICTATION_SYSTEM_PROMPT}
+
+# Each variant flips one thing relative to "A" (the known-good pipeline recipe).
+VARIANTS = {
+    "A  pipeline recipe (user-only, pipeline sampling, 1024)": {
+        "messages": [USER_MSG], "max_tokens": 1024, **PIPELINE_SAMPLING},
+    "B  +system role (pipeline sampling)": {
+        "messages": [SYSTEM_MSG, USER_MSG], "max_tokens": 1024, **PIPELINE_SAMPLING},
+    "C  app sampling, user-only": {
+        "messages": [USER_MSG], "max_tokens": 512, **APP_SAMPLING},
+    "D  full app config (system + app sampling, 512)": {
+        "messages": [SYSTEM_MSG, USER_MSG], "max_tokens": 512, **APP_SAMPLING},
+    # E: the fix — same as D but with the larger budget now in app.py.
+    "E  FIX: app config + max_tokens 2048": {
+        "messages": [SYSTEM_MSG, USER_MSG], "max_tokens": 2048, **APP_SAMPLING},
+    # F: better optimization — ask the server to skip thinking entirely. If the
+    #    LFM2.5 chat template honors this, reasoning_content vanishes and a small
+    #    budget suffices again (faster, cheaper). If ignored, behaves like D.
+    "F  try disable thinking (chat_template_kwargs, 512)": {
+        "messages": [SYSTEM_MSG, USER_MSG], "max_tokens": 512,
+        "chat_template_kwargs": {"enable_thinking": False}, **APP_SAMPLING},
+}
+
+
+def run(name: str, extra: dict) -> None:
+    payload = {"model": MODEL, **extra}
+    print(f"\n===== {name} =====")
+    try:
+        r = requests.post(ENDPOINT, json=payload, timeout=900)
+        r.raise_for_status()
+        data = r.json()
+    except Exception as e:
+        print("  REQUEST FAILED:", e)
+        return
+    choice = (data.get("choices") or [{}])[0]
+    msg = choice.get("message") or {}
+    content = msg.get("content")
+    print("  finish_reason:", choice.get("finish_reason"))
+    print("  content len   :", len(content or ""))
+    print("  content repr  :", repr(content)[:300])
+    # Surface any non-standard fields (reasoning channel, etc.).
+    extra_keys = {k: v for k, v in msg.items() if k not in ("role", "content")}
+    if extra_keys:
+        print("  other message keys:", json.dumps(extra_keys, ensure_ascii=False)[:300])
+    if not (content or "").strip():
+        print("  >> EMPTY. full response:", json.dumps(data, ensure_ascii=False)[:1500])
+
+
+if __name__ == "__main__":
+    print("endpoint:", ENDPOINT)
+    for name, extra in VARIANTS.items():
+        run(name, extra)

diff_html.py

@@ -0,0 +1,67 @@
+"""Render a GradeReport as color-coded HTML for the Gradio Space.
+
+This is the presentation layer over the deterministic grader in
+space.ocr.grading (spec §7): the diff and score are computed there; here we
+only turn the report into spans the learner can read. Pure, no network.
+"""
+
+import html
+
+try:  # package context (space.diff_html, e.g. tests at repo root)
+    from .ocr.grading import GradeReport
+except ImportError:  # flat context (HF Space root, app.py)
+    from ocr.grading import GradeReport
+
+# Inline styles (Gradio sanitizes <style> blocks; inline survives).
+_CORRECT = "color:#16794a;"
+_WRONG = "color:#c0392b;font-weight:600;"
+_MISSING = "color:#b9770e;font-style:italic;"
+_EXTRA = "color:#8e44ad;font-style:italic;text-decoration:line-through;"
+
+
+def _verdict(accuracy: float) -> str:
+    if accuracy >= 0.95:
+        return "Excellent"
+    if accuracy >= 0.8:
+        return "Good"
+    if accuracy >= 0.6:
+        return "Keep practicing"
+    return "Needs work"
+
+
+def render_report_html(report: GradeReport) -> str:
+    """Color-coded word-level diff plus a score header (spec §7)."""
+    s = report.summary
+    score = round(s.accuracy * 100)
+
+    spans: list[str] = []
+    for w in report.words:
+        if w.status == "correct":
+            spans.append(f'<span style="{_CORRECT}">{html.escape(w.read or "")}</span>')
+        elif w.status == "misspelled":
+            wrote = html.escape(w.read or "")
+            correct = html.escape(w.expected or "")
+            spans.append(
+                f'<span style="{_WRONG}" title="{html.escape(w.diff or "")}">'
+                f"{wrote} → {correct}</span>"
+            )
+        elif w.status == "missing":
+            spans.append(
+                f'<span style="{_MISSING}">[missing: {html.escape(w.expected or "")}]</span>'
+            )
+        else:  # extra
+            spans.append(
+                f'<span style="{_EXTRA}">[extra: {html.escape(w.read or "")}]</span>'
+            )
+
+    body = " ".join(spans) if spans else "<em>No text recognized.</em>"
+
+    return (
+        f'<div style="font-size:1.05rem;line-height:1.7;">'
+        f'<p style="font-size:1.2rem;margin:0 0 .4rem;">'
+        f"<strong>{score}%</strong> &middot; {_verdict(s.accuracy)} "
+        f'<span style="color:#666;">({s.correct}/{s.total} correct, '
+        f"misspelled {s.misspelled}, missing {s.missing}, extra {s.extra})</span></p>"
+        f"<p>{body}</p>"
+        f"</div>"
+    )

ocr/grading.py

@@ -0,0 +1,236 @@
+"""Deterministic dictation grading: align a blind transcription against a
+known reference and emit a strict JSON report.
+
+See specs/ocr.md. The VLM transcription step lives elsewhere; this module
+never sees the image and is fully testable with a fixed transcription string.
+"""
+
+import re
+import unicodedata
+from difflib import SequenceMatcher
+from typing import Literal, NamedTuple
+
+from pydantic import BaseModel
+
+Status = Literal["correct", "misspelled", "missing", "extra"]
+
+# A word is a maximal run of word characters (Unicode letters/digits/_);
+# any other non-space character is a standalone punctuation token.
+_TOKEN_RE = re.compile(r"\w+|[^\w\s]", re.UNICODE)
+
+
+class Token(NamedTuple):
+    text: str
+    is_word: bool
+
+
+class GradeOptions(NamedTuple):
+    """Pedagogy knobs for grading (see specs/ocr.md §8). Defaults match the
+    spec: case matters, punctuation is reported but not counted, diacritics
+    are graded."""
+
+    case_sensitive: bool = True
+    grade_punctuation: bool = False
+    grade_diacritics: bool = True
+
+
+def comparison_key(word: str, options: GradeOptions) -> str:
+    """Map a surface word to the key used for alignment/equality, applying the
+    active grading options. The surface form is preserved for display; only
+    this key decides whether two words count as 'the same'.
+
+    Never maps ß→ss or ö→oe — diacritic *grading* only strips combining marks
+    (accents), and ß is not a combining mark, so it always stays distinct."""
+    key = unicodedata.normalize("NFC", word)
+    if not options.case_sensitive:
+        key = key.casefold()
+    if not options.grade_diacritics:
+        decomposed = unicodedata.normalize("NFD", key)
+        key = "".join(ch for ch in decomposed if not unicodedata.combining(ch))
+        key = unicodedata.normalize("NFC", key)
+    return key
+
+
+def tokenize(text: str) -> list[Token]:
+    """NFC-normalize then split into word and punctuation tokens."""
+    text = unicodedata.normalize("NFC", text)
+    tokens: list[Token] = []
+    for match in _TOKEN_RE.finditer(text):
+        piece = match.group()
+        tokens.append(Token(piece, is_word=bool(re.match(r"\w", piece))))
+    return tokens
+
+
+def graphemes(text: str) -> list[str]:
+    """Split a string into grapheme clusters (a base char plus any trailing
+    combining marks), so combining diacritics don't desync a character diff."""
+    clusters: list[str] = []
+    for ch in text:
+        if clusters and unicodedata.combining(ch):
+            clusters[-1] += ch
+        else:
+            clusters.append(ch)
+    return clusters
+
+
+def char_diff(expected: str, read: str) -> str:
+    """Human-readable grapheme-level diff describing how ``read`` deviates from
+    ``expected`` (e.g. ``ß→ss``, ``-t``, ``+e``). Empty string if identical."""
+    a, b = graphemes(expected), graphemes(read)
+    parts: list[str] = []
+    for op, i1, i2, j1, j2 in SequenceMatcher(a=a, b=b).get_opcodes():
+        if op == "equal":
+            continue
+        exp_chunk, read_chunk = "".join(a[i1:i2]), "".join(b[j1:j2])
+        if op == "replace":
+            parts.append(f"{exp_chunk}→{read_chunk}")
+        elif op == "delete":
+            parts.append(f"-{exp_chunk}")
+        elif op == "insert":
+            parts.append(f"+{read_chunk}")
+    return ", ".join(parts)
+
+
+class Word(BaseModel):
+    """One graded word in the report (specs/ocr.md §7).
+
+    ``expected`` is None for ``extra``; ``read`` is None for ``missing``;
+    ``diff`` is present only for ``misspelled``."""
+
+    index: int
+    expected: str | None
+    read: str | None
+    status: Status
+    diff: str | None = None
+
+
+def _word_texts(text: str, options: GradeOptions) -> list[str]:
+    """Token surface forms to align: words always, punctuation only when graded."""
+    return [
+        tok.text
+        for tok in tokenize(text)
+        if tok.is_word or options.grade_punctuation
+    ]
+
+
+def align_words(
+    reference: str, transcription: str, options: GradeOptions | None = None
+) -> list[Word]:
+    """Align the blind transcription against the reference at word level and
+    classify each token (specs/ocr.md stages 3-4). Deterministic, no model."""
+    options = options or GradeOptions()
+    ref = _word_texts(reference, options)
+    read = _word_texts(transcription, options)
+    ref_keys = [comparison_key(w, options) for w in ref]
+    read_keys = [comparison_key(w, options) for w in read]
+
+    words: list[Word] = []
+
+    def emit(expected: str | None, got: str | None, status: Status) -> None:
+        diff = char_diff(expected, got) if status == "misspelled" else None
+        words.append(
+            Word(
+                index=len(words),
+                expected=expected,
+                read=got,
+                status=status,
+                diff=diff or None,
+            )
+        )
+
+    for op, i1, i2, j1, j2 in SequenceMatcher(a=ref_keys, b=read_keys).get_opcodes():
+        if op == "equal":
+            for i, j in zip(range(i1, i2), range(j1, j2)):
+                emit(ref[i], read[j], "correct")
+        elif op == "replace":
+            # Pair up as misspellings; leftovers are missing/extra.
+            paired = min(i2 - i1, j2 - j1)
+            for k in range(paired):
+                emit(ref[i1 + k], read[j1 + k], "misspelled")
+            for i in range(i1 + paired, i2):
+                emit(ref[i], None, "missing")
+            for j in range(j1 + paired, j2):
+                emit(None, read[j], "extra")
+        elif op == "delete":
+            for i in range(i1, i2):
+                emit(ref[i], None, "missing")
+        elif op == "insert":
+            for j in range(j1, j2):
+                emit(None, read[j], "extra")
+
+    return words
+
+
+class Summary(BaseModel):
+    """Tally over the graded words. ``total`` counts reference words only
+    (correct + misspelled + missing); extras don't inflate it."""
+
+    total: int
+    correct: int
+    misspelled: int
+    missing: int
+    extra: int
+    accuracy: float
+
+
+class GradeReport(BaseModel):
+    """The strict JSON grading report (specs/ocr.md §7)."""
+
+    lang: str
+    reference: str
+    transcription: str
+    words: list[Word]
+    summary: Summary
+
+
+def _summarize(words: list[Word]) -> Summary:
+    counts = {"correct": 0, "misspelled": 0, "missing": 0, "extra": 0}
+    for w in words:
+        counts[w.status] += 1
+    total = counts["correct"] + counts["misspelled"] + counts["missing"]
+    accuracy = round(counts["correct"] / total, 4) if total else 0.0
+    return Summary(total=total, accuracy=accuracy, **counts)
+
+
+def grade(
+    reference: str,
+    transcription: str,
+    lang: str,
+    options: GradeOptions | None = None,
+) -> GradeReport:
+    """Grade a blind transcription against the reference and return a validated
+    report (specs/ocr.md stages 3-5). The image/VLM never enters here."""
+    options = options or GradeOptions()
+    words = align_words(reference, transcription, options)
+    return GradeReport(
+        lang=lang,
+        reference=unicodedata.normalize("NFC", reference),
+        transcription=unicodedata.normalize("NFC", transcription),
+        words=words,
+        summary=_summarize(words),
+    )
+
+
+_MARKS = {"correct": "✓", "misspelled": "✗", "missing": "·", "extra": "+"}
+
+
+def format_text_report(report: GradeReport) -> str:
+    """Render a GradeReport as a human-readable plain-text report (derivable
+    purely from the JSON, specs/ocr.md §2)."""
+    s = report.summary
+    lines = [
+        f"[{report.lang}] {s.correct}/{s.total} correct "
+        f"({s.accuracy * 100:.0f}%)  "
+        f"misspelled={s.misspelled} missing={s.missing} extra={s.extra}",
+    ]
+    for w in report.words:
+        mark = _MARKS[w.status]
+        if w.status == "correct":
+            lines.append(f"  {mark} {w.read}")
+        elif w.status == "misspelled":
+            lines.append(f"  {mark} {w.expected} → {w.read}  [{w.diff}]")
+        elif w.status == "missing":
+            lines.append(f"  {mark} {w.expected}  (missing)")
+        else:  # extra
+            lines.append(f"  {mark} {w.read}  (extra)")
+    return "\n".join(lines)

ocr/transcribe.py

@@ -0,0 +1,96 @@
+"""Blind handwriting transcription via an OpenAI-compatible VLM (Qwen3-VL on
+Modal, see modal/ocr/modal_qwen3vl.py).
+
+The one rule (specs/ocr.md §3): this module NEVER sees the reference text. It
+asks the model for a faithful, uncorrected transcription of the page; grading
+happens afterwards in ocr.grading. Note there is deliberately no ``reference``
+parameter anywhere here."""
+
+import base64
+import json
+import mimetypes
+from pathlib import Path
+
+# specs/ocr.md §10, hardened. The "word by word" + explicit spelling-error +
+# umlaut-dot framing beat both the original prompt and a "letter by letter"
+# variant on a real handwriting sample: on Qwen3-VL-8B it fixed gross misreads
+# without adding noise. The one residual failure is the language-model prior
+# auto-correcting missing umlauts on very common words (e.g. a deliberately
+# written "Fruhstück" still came back "Frühstück") — see specs/ocr.md §9.
+SYSTEM_PROMPT = (
+    "You are a forensic handwriting transcriber. Transcribe the page WORD BY "
+    "WORD, copying each written word exactly as it appears on the paper.\n"
+    "\n"
+    "This text was written in a SPELLING TEST and DELIBERATELY CONTAINS "
+    "SPELLING ERRORS. Reproduce every error faithfully. NEVER replace a word "
+    "with its dictionary-correct spelling. If a word is written wrong, "
+    "transcribe it exactly as wrongly written.\n"
+    "\n"
+    "Umlaut rule (critical): write a/o/u with two dots (a->ä, o->ö, u->ü) ONLY "
+    "when you can clearly see two dots above that exact letter. If a u, a or o "
+    "has NO dots above it, keep it plain (u, a, o) even if correct German would "
+    "use an umlaut. Never add dots that are not on the page; never drop dots "
+    "that are.\n"
+    "Do NOT change ß to ss or ss to ß. Do NOT translate. Do NOT fix spacing, "
+    "grammar, or capitalization.\n"
+    "Output ONLY the transcribed text, one line per written line."
+)
+
+USER_INSTRUCTION = (
+    "Transcribe this page word by word, reproducing every spelling error "
+    "exactly as written."
+)
+
+def guess_mime(path: str) -> str:
+    """MIME type for an image path, defaulting to PNG."""
+    mime, _ = mimetypes.guess_type(path)
+    return mime or "image/png"
+
+
+def data_uri(image_bytes: bytes, mime: str) -> str:
+    """Encode raw image bytes as an OpenAI ``image_url`` data URI."""
+    b64 = base64.b64encode(image_bytes).decode("ascii")
+    return f"data:{mime};base64,{b64}"
+
+
+def encode_image(path: str) -> str:
+    """Read an image file and return its data URI."""
+    return data_uri(Path(path).read_bytes(), guess_mime(path))
+
+
+def build_payload(image_uri: str, model: str, temperature: float = 0.0) -> dict:
+    """Build the chat-completion request for a blind transcription. No
+    reference text appears anywhere (specs/ocr.md §3)."""
+    return {
+        "model": model,
+        "temperature": temperature,
+        "messages": [
+            {"role": "system", "content": SYSTEM_PROMPT},
+            {
+                "role": "user",
+                "content": [
+                    {"type": "text", "text": USER_INSTRUCTION},
+                    {"type": "image_url", "image_url": {"url": image_uri}},
+                ],
+            },
+        ],
+    }
+
+
+def parse_response(data: dict) -> str:
+    """Extract the transcription text from an OpenAI-style response dict."""
+    try:
+        return data["choices"][0]["message"]["content"].strip()
+    except (KeyError, IndexError, TypeError, AttributeError) as e:
+        raise ValueError(f"Unexpected VLM response: {json.dumps(data)[:500]}") from e
+
+
+def transcribe_image(image_path: str, client, model: str = "qwen3-vl") -> str:
+    """Transcribe a handwritten page blind.
+
+    ``client`` is an OpenAI-compatible client pointed at the Modal VLM server
+    (build one with ``openai_client.make_client``). Cold-start retries live in
+    the client, not here."""
+    payload = build_payload(encode_image(image_path), model)
+    completion = client.chat.completions.create(**payload)
+    return parse_response(completion.model_dump())

openai_client.py

@@ -0,0 +1,70 @@
+"""Shared OpenAI-compatible client factory for the Modal endpoints.
+
+All three models (LFM2.5 text, Higgs TTS, Qwen3-VL OCR) speak the OpenAI HTTP
+API, so a single ``OpenAI`` client talks to each — only the base URL differs.
+
+The one project-specific concern lives here: **Modal cold starts.** An idle
+container answers the first request with a 502/503/504 while it boots (~30-60 s,
+see app.py COLD_START_HINT). The SDK already retries 5xx/connection errors with
+exponential backoff; we just raise ``max_retries`` and ``timeout`` well past the
+SDK defaults (2 retries) so a cold boot is absorbed rather than surfaced.
+
+This module is intentionally self-contained (no intra-package imports) so it can
+be imported both as ``openai_client`` (from the Space root) and
+``space.openai_client`` (from the repo root) — the same dual-path trick the
+``ocr`` package relies on.
+"""
+
+import os
+
+from openai import OpenAI
+
+TIMEOUT = 900  # seconds; headroom for a Modal cold start
+MAX_RETRIES = 15  # SDK backoff caps each sleep at ~8 s -> covers a ~1-2 min boot
+
+# Modal endpoints don't authenticate the OpenAI API key, but the SDK requires a
+# non-empty one. (Proxy auth, below, is a separate Modal-Key/Modal-Secret pair.)
+DUMMY_API_KEY = "EMPTY"
+
+# Modal proxy auth: when an endpoint is deployed with requires_proxy_auth=True,
+# every request must carry these two headers, sourced from a proxy auth token.
+MODAL_KEY_ENV = "MODAL_KEY"
+MODAL_SECRET_ENV = "MODAL_SECRET"
+
+
+def proxy_auth_headers() -> dict[str, str]:
+    """Modal proxy-auth headers from the environment, or empty if not configured.
+
+    Both halves are required, so a lone key/secret yields nothing — the client
+    stays unauthenticated and keeps working against unprotected endpoints until
+    both ``MODAL_KEY`` and ``MODAL_SECRET`` are set."""
+    key = os.environ.get(MODAL_KEY_ENV)
+    secret = os.environ.get(MODAL_SECRET_ENV)
+    if key and secret:
+        return {"Modal-Key": key, "Modal-Secret": secret}
+    return {}
+
+
+def make_client(
+    base_url: str,
+    *,
+    timeout: float = TIMEOUT,
+    max_retries: int = MAX_RETRIES,
+) -> OpenAI:
+    """Build an OpenAI client pointed at a Modal server.
+
+    ``base_url`` may be the server root or already include the ``/v1`` suffix;
+    both are accepted (and a trailing slash is fine). Modal proxy-auth headers
+    are attached automatically when configured (see ``proxy_auth_headers``).
+    """
+    base = base_url.rstrip("/")
+    if not base.endswith("/v1"):
+        base = f"{base}/v1"
+    headers = proxy_auth_headers()
+    return OpenAI(
+        base_url=base,
+        api_key=DUMMY_API_KEY,
+        timeout=timeout,
+        max_retries=max_retries,
+        default_headers=headers or None,
+    )

prompts.py

@@ -0,0 +1,53 @@
+"""Dictation generation prompt + light text cleanup for the Gradio Space.
+
+The LLM turns a learner's word list + CEFR level into ONE short German
+dictation paragraph. This is distinct from the Anki flashcard prompts in
+sys.md / sys1.md, which emit JSON — here we want plain prose to be read aloud.
+"""
+
+import re
+
+DICTATION_SYSTEM_PROMPT = (
+    "You are a German teacher writing a short dictation (Diktat) for a language "
+    "learner.\n"
+    "\n"
+    "Write ONE coherent German paragraph of 2-4 natural, everyday sentences that "
+    "uses EVERY target word the user provides at least once (inflect it naturally; "
+    "the exact base form need not appear). The text must suit the given CEFR level:\n"
+    "- A1/A2: short main clauses, common vocabulary, present tense, simple word order.\n"
+    "- B1/B2: allow subordinate clauses, connectors and varied tenses, still everyday.\n"
+    "\n"
+    "Use correct standard German spelling, capitalization, umlauts (ä/ö/ü) and ß.\n"
+    "Output ONLY the German dictation text. No title, no label, no quotation marks, "
+    "no translation, no commentary, no markdown."
+)
+
+
+def build_user_prompt(words: list[str], level: str) -> str:
+    """The user turn: the target words and the requested level."""
+    joined = ", ".join(words)
+    return f"Level: {level}\nTarget words: {joined}"
+
+
+def parse_word_list(raw: str) -> list[str]:
+    """Split learner input on commas and/or newlines into trimmed words,
+    dropping blanks while preserving order (spec §4)."""
+    parts = re.split(r"[,\n]+", raw or "")
+    return [w.strip() for w in parts if w.strip()]
+
+
+_LABEL_RE = re.compile(r"^\s*(diktat|dictation|text)\s*:\s*", re.IGNORECASE)
+
+
+def clean_dictation(text: str) -> str:
+    """Strip a leading label line (e.g. 'Diktat:') and wrapping quotes the LLM
+    may add despite instructions (spec §4)."""
+    text = (text or "").strip()
+    text = _LABEL_RE.sub("", text, count=1).strip()
+    # Strip one layer of matching surrounding quotes (straight or typographic).
+    pairs = [('"', '"'), ("'", "'"), ("“", "”"), ("„", "“")]
+    for open_q, close_q in pairs:
+        if len(text) >= 2 and text[0] == open_q and text[-1] == close_q:
+            text = text[1:-1].strip()
+            break
+    return text

requirements.txt

@@ -0,0 +1,5 @@
+gradio==6.18.0
+requests
+openai>=2,<3
+pydantic
+loguru

wizard.py

@@ -0,0 +1,20 @@
+"""Navigation for the 4-step dictation wizard.
+
+The UI is four ``gr.Group`` views stacked in one column; exactly one is visible
+at a time. ``nav`` is the single source of truth for "show this step, hide the
+rest" — handlers append its result to their outputs to move between steps. Kept
+free of flat ``app`` imports so it can be imported both as ``wizard`` (Space
+root) and ``space.wizard`` (repo root), and unit-tested without the app."""
+
+import gradio as gr
+
+# Order matters: it's the order the view Groups are created in build_ui and the
+# order nav() returns visibility updates.
+VIEWS = ("input", "listen", "upload", "results")
+
+
+def nav(target: str) -> list:
+    """Visibility updates for the four views; only ``target`` is shown."""
+    if target not in VIEWS:
+        raise ValueError(f"unknown view: {target!r} (expected one of {VIEWS})")
+    return [gr.update(visible=(view == target)) for view in VIEWS]