Upload 4 files

.gitattributes

@@ -0,0 +1,4 @@
+*.gguf filter=lfs diff=lfs merge=lfs -text
+*.bin  filter=lfs diff=lfs merge=lfs -text
+*.pt   filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text

README.md

@@ -0,0 +1,58 @@
+---
+title: Spelling Practice
+emoji: 📝
+colorFrom: indigo
+colorTo: purple
+sdk: gradio
+sdk_version: "4.40.0"
+app_file: app.py
+pinned: false
+license: mit
+---
+
+# Spelling Practice 📝
+
+An interactive English spelling trainer powered by gTTS (audio) and optionally Gemma (AI tips).
+
+## How to use
+
+1. Click **New Sentence** — a sentence is read aloud.
+2. Type exactly what you heard in the text box.
+3. Click **Submit** (or press Enter).
+4. Errors are shown with strikethrough (~~wrong~~) and the **correct** word in bold.
+5. Get 3 correct answers in a row to level up.
+
+## Difficulty levels
+
+| Level | Label |
+|-------|-------|
+| 1 | 🟢 Beginner |
+| 2 | 🔵 Intermediate |
+| 3 | 🟠 Advanced |
+| 4 | 🔴 Expert |
+
+## Multi-user support
+
+Every browser session gets its own isolated state via `gr.State`.  
+Concurrent users don't share or interfere with each other.
+
+## Optional: AI Tips with Gemma
+
+To enable in-app spelling tips from a local LLM:
+
+1. Upload a `.gguf` model file to your Space repository (e.g. `gemma-4-E2B-it-Q4_0.gguf`).
+2. Uncomment `llama-cpp-python` in `requirements.txt`.
+3. If your Space has a GPU, replace the pip line with the CUDA wheel:
+   ```
+   llama-cpp-python --extra-index-url https://abetlen.github.io/llama-cpp-python/whl/cu121
+   ```
+4. Set the `N_GPU_LAYERS` Space secret to `-1` (full GPU offload) or `0` (CPU only).
+
+Without a model file the app runs fine — the tip section is simply hidden.
+
+## Local development
+
+```bash
+pip install gradio gTTS
+python app.py
+```

app.py

@@ -0,0 +1,348 @@
+"""
+Spelling Practice – Hugging Face Space
+Multi-user safe: all mutable state lives in gr.State (one copy per browser session).
+"""
+
+import os
+import glob
+import random
+import tempfile
+import difflib
+import json
+import time
+import threading
+from pathlib import Path
+
+import gradio as gr
+from gtts import gTTS
+
+# ── Optional: llama-cpp for Gemma tips ────────────────────────────────────────
+try:
+    from llama_cpp import Llama
+    _LLAMA_AVAILABLE = True
+except ImportError:
+    _LLAMA_AVAILABLE = False
+
+# ── Model loading (shared across all users, loaded once at startup) ────────────
+_llm = None
+_llm_lock = threading.Lock()
+
+def get_llm():
+    """Return the shared Llama instance, loading it on first call."""
+    global _llm
+    if _llm is not None:
+        return _llm
+    if not _LLAMA_AVAILABLE:
+        return None
+    with _llm_lock:
+        if _llm is not None:
+            return _llm
+        gguf_files = glob.glob("/app/*.gguf") + glob.glob("*.gguf")
+        if not gguf_files:
+            print("[spelling-app] No .gguf file found – AI tips disabled.")
+            return None
+        model_path = gguf_files[0]
+        print(f"[spelling-app] Loading model: {model_path}")
+        _llm = Llama(
+            model_path=model_path,
+            n_ctx=512,
+            n_threads=2,
+            n_gpu_layers=int(os.getenv("N_GPU_LAYERS", "-1")),
+            verbose=False,
+        )
+        print("[spelling-app] Model ready.")
+        return _llm
+
+# ── Sentence bank ──────────────────────────────────────────────────────────────
+SENTENCES = {
+    "easy": [
+        "The student read a book.",
+        "I like to learn English.",
+        "The bank has no money.",
+        "She has a new job.",
+        "He can read very fast.",
+        "The map shows a river.",
+        "We write notes in class.",
+        "Put the book on the desk.",
+        "I see a small farm.",
+        "The goal is very clear.",
+    ],
+    "medium": [
+        "The Southern colonies grew tobacco for Europe.",
+        "The workers found jobs in the factory.",
+        "He forgot to cite the original source.",
+        "They experienced a major economic boom.",
+        "My teacher helps me write better essays.",
+        "The market was very weak in December.",
+        "She received a new evening gown quickly.",
+        "We need to manage our time properly.",
+        "The group discussion went very well.",
+        "The online platform closes at midnight.",
+    ],
+    "hard": [
+        "The government announced policies to address the downturn.",
+        "She has an extraordinary talent for analyzing economic literature.",
+        "The archaeologist made a fascinating discovery of ancient artifacts.",
+        "It is necessary to manage your time effectively.",
+        "The corporation was highly profitable after the merger.",
+        "He struggled to translate the complex economic metaphors.",
+        "The instructor approved the research outline immediately.",
+        "She demonstrated remarkable perseverance throughout her academic journey.",
+        "Maintaining a regular study schedule is very important.",
+        "The researcher examined the primary historical document.",
+    ],
+    "expert": [
+        "The multinational corporation acknowledged the financial discrepancy.",
+        "His idiosyncratic research methodologies bewildered his academic colleagues.",
+        "The distinguished economist delivered a highly influential speech.",
+        "Technological advancements fundamentally transformed nineteenth-century transportation.",
+        "Maslow conceptualized self-actualization as the highest human need.",
+        "Agricultural consolidation overwhelmed small family farming operations.",
+        "Translating metaphorical expressions requires extraordinary cultural competence.",
+        "Plagiarism often leads to severe academic consequences.",
+        "The entrepreneur demonstrated extraordinary economic decision-making.",
+        "The researcher meticulously catalogued primary historical sources.",
+    ],
+}
+
+LEVELS       = ["easy", "medium", "hard", "expert"]
+LEVEL_LABELS = ["🟢 Beginner", "🔵 Intermediate", "🟠 Advanced", "🔴 Expert"]
+PASS_REQ     = 3
+
+
+# ── Per-user state ─────────────────────────────────────────────────────────────
+
+def fresh_state():
+    return {
+        "level":    0,
+        "streak":   0,
+        "sentence": "",
+        "score":    0,
+        "total":    0,
+        "history":  [],
+    }
+
+
+# ── Core helpers ───────────────────────────────────────────────────────────────
+
+def _make_audio(text):
+    try:
+        tts  = gTTS(text=text, lang="en", slow=True)
+        path = tempfile.mktemp(suffix=".mp3")
+        tts.save(path)
+        return path
+    except Exception as exc:
+        print(f"[spelling-app] gTTS error: {exc}")
+        return None
+
+
+def _find_errors(correct, attempt):
+    c_words = correct.rstrip(".").lower().split()
+    a_words = attempt.rstrip(".").lower().split()
+    errors  = []
+    matcher = difflib.SequenceMatcher(None, a_words, c_words)
+    for tag, i1, i2, j1, j2 in matcher.get_opcodes():
+        if tag == "replace":
+            for w, r in zip(a_words[i1:i2], c_words[j1:j2]):
+                if w != r:
+                    errors.append((w, r))
+        elif tag == "delete":
+            for w in a_words[i1:i2]:
+                errors.append((w, "[extra word]"))
+        elif tag == "insert":
+            for r in c_words[j1:j2]:
+                errors.append(("[missing]", r))
+    return errors
+
+
+def _ask_gemma(correct, attempt, errors):
+    llm = get_llm()
+    if not llm or not errors:
+        return ""
+    error_list = "\n".join(
+        f'- You wrote "{w}", correct is "{r}"' for w, r in errors
+    )
+    prompt = (
+        "You are a friendly English spelling teacher.\n"
+        f"The student had to write: {correct}\n"
+        f"The student wrote:        {attempt}\n"
+        f"Spelling mistakes:\n{error_list}\n\n"
+        "For each mistake, write one short sentence explaining the error "
+        "and one memory tip. Be encouraging. Keep it brief."
+    )
+    out = llm(prompt, max_tokens=200, temperature=0.3, stop=["###"])
+    return out["choices"][0]["text"].strip()
+
+
+def _build_diff(correct, attempt):
+    c_words = correct.split()
+    a_words = attempt.split()
+    parts   = []
+    sm = difflib.SequenceMatcher(
+        None,
+        [w.rstrip(".,").lower() for w in a_words],
+        [w.rstrip(".,").lower() for w in c_words],
+    )
+    for tag, i1, i2, j1, j2 in sm.get_opcodes():
+        if tag == "equal":
+            parts.append(" ".join(a_words[i1:i2]))
+        elif tag == "replace":
+            parts.append(
+                "~~" + " ".join(a_words[i1:i2])
+                + "~~ **" + " ".join(c_words[j1:j2]) + "**"
+            )
+        elif tag == "delete":
+            parts.append("~~" + " ".join(a_words[i1:i2]) + "~~")
+        elif tag == "insert":
+            parts.append("**[" + " ".join(c_words[j1:j2]) + "]**")
+    return " ".join(parts)
+
+
+def _level_info(state):
+    lvl   = state["level"]
+    label = LEVEL_LABELS[lvl]
+    extra = (
+        f"  ·  streak {state['streak']}/{PASS_REQ} to level up"
+        if lvl < len(LEVELS) - 1
+        else "  ·  MAX LEVEL 🏆"
+    )
+    return f"**{label}**{extra}"
+
+
+def _score_info(state):
+    t   = state["total"]
+    s   = state["score"]
+    pct = int(s / t * 100) if t else 0
+    return f"**Score: {s}/{t}** ({pct}%)"
+
+
+# ── Event handlers ─────────────────────────────────────────────────────────────
+
+def new_sentence(state):
+    sent  = random.choice(SENTENCES[LEVELS[state["level"]]])
+    state = {**state, "sentence": sent}
+    audio = _make_audio(sent)
+    hint  = "🎧 Listen carefully, then type what you heard and press **Submit**."
+    if audio is None:
+        hint = f"⚠️ Audio unavailable. Sentence: **{sent}**  *(type it below)*"
+    return audio, "", hint, _level_info(state), _score_info(state), state
+
+
+def submit_answer(attempt, state):
+    if not state.get("sentence"):
+        return "", "⚠️ Press **New Sentence** first!", _level_info(state), _score_info(state), state
+
+    correct = state["sentence"]
+    state   = {**state, "total": state["total"] + 1}
+    errors  = _find_errors(correct, attempt)
+    clean_a = attempt.strip().rstrip(".").lower()
+    clean_c = correct.strip().rstrip(".").lower()
+
+    if not errors and clean_a == clean_c:
+        state = {**state, "score": state["score"] + 1, "streak": state["streak"] + 1}
+        msg = "✅ **Correct!** Every word spelled perfectly."
+        if state["streak"] >= PASS_REQ and state["level"] < len(LEVELS) - 1:
+            state = {**state, "level": state["level"] + 1, "streak": 0}
+            new_label = LEVEL_LABELS[state["level"]]
+            msg += f"\n\n🎉 **Level up! You are now {new_label}.**"
+    else:
+        state     = {**state, "streak": 0}
+        diff_str  = _build_diff(correct, attempt)
+        gemma_tip = _ask_gemma(correct, attempt, errors)
+        ai_block  = (
+            f"\n\n---\n\n**💡 Tips:**\n\n{gemma_tip}"
+            if gemma_tip
+            else ""
+        )
+        msg = (
+            "❌ **Your answer with corrections:**\n\n"
+            + diff_str
+            + "\n\n*(~~strikethrough~~ = your error · **bold** = correct spelling)*"
+            + ai_block
+        )
+
+    entry = {
+        "correct": correct,
+        "attempt": attempt,
+        "ok": not bool(errors) and clean_a == clean_c,
+        "level": LEVELS[state["level"]],
+        "ts": time.strftime("%H:%M:%S"),
+    }
+    state = {**state, "sentence": "", "history": state["history"] + [entry]}
+    return attempt, msg, _level_info(state), _score_info(state), state
+
+
+def replay_audio(state):
+    if state.get("sentence"):
+        return _make_audio(state["sentence"])
+    return None
+
+
+def reset_game(state):
+    state = fresh_state()
+    return None, "", "Game reset. Press **New Sentence** to start!", _level_info(state), _score_info(state), state
+
+
+def export_history(state):
+    history = state.get("history", [])
+    if not history:
+        return None
+    path = tempfile.mktemp(suffix=".json")
+    with open(path, "w") as f:
+        json.dump(history, f, indent=2, ensure_ascii=False)
+    return path
+
+
+# ── UI ─────────────────────────────────────────────────────────────────────────
+
+CSS = """
+body { font-family: 'Segoe UI', sans-serif; }
+footer { display: none !important; }
+"""
+
+with gr.Blocks(title="Spelling Practice") as demo:
+
+    session = gr.State(fresh_state)
+
+    gr.Markdown(
+        "# 📝 Spelling Practice\n"
+        "Listen to the sentence · Type it · See errors highlighted · Get AI tips"
+    )
+
+    with gr.Row():
+        level_md = gr.Markdown(_level_info(fresh_state()))
+        score_md = gr.Markdown(_score_info(fresh_state()))
+
+    with gr.Row():
+        new_btn    = gr.Button("🎲 New Sentence", variant="primary")
+        replay_btn = gr.Button("🔁 Replay Audio", variant="secondary")
+        reset_btn  = gr.Button("🔄 Reset Game",   variant="secondary")
+
+    audio_out  = gr.Audio(label="Listen to the sentence", autoplay=True, interactive=False)
+    hint_md    = gr.Markdown("Press **New Sentence** to begin.")
+    answer_box = gr.Textbox(
+        label="Type the sentence you heard",
+        placeholder="Write the full sentence here…",
+        lines=2,
+    )
+    submit_btn = gr.Button("✅ Submit", variant="primary")
+    feedback   = gr.Markdown("")
+
+    with gr.Accordion("📊 Session History", open=False):
+        export_btn   = gr.Button("⬇️ Export history (JSON)")
+        history_file = gr.File(label="Download", visible=True)
+
+    OUTS = [audio_out, answer_box, hint_md, level_md, score_md, session]
+
+    new_btn.click(new_sentence,    [session],              OUTS)
+    replay_btn.click(replay_audio, [session],              [audio_out])
+    submit_btn.click(submit_answer,[answer_box, session],  [answer_box, feedback, level_md, score_md, session])
+    answer_box.submit(submit_answer,[answer_box, session], [answer_box, feedback, level_md, score_md, session])
+    reset_btn.click(reset_game,    [session],              OUTS)
+    export_btn.click(export_history,[session],             [history_file])
+
+if __name__ == "__main__":
+    demo.launch(
+        css=CSS,
+        share=False,
+    )

requirements.txt

@@ -0,0 +1,6 @@
+gradio>=4.40.0
+gTTS>=2.5.0
+# llama-cpp-python is optional – uncomment the line below only if you
+# upload a .gguf model file to the Space repository.
+# If your Space has a GPU, use the CUDA wheel instead; see README.
+# llama-cpp-python>=0.2.77