Upload folder using huggingface_hub

README.md

@@ -1,12 +1,9 @@
----
-title: Agentic Language Partner
-emoji: 🔥
-colorFrom: green
-colorTo: yellow
-sdk: gradio
-sdk_version: 6.0.1
-app_file: app.py
-pinned: false
----
+# Agentic Language Partner
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+Deployed automatically from Google Colab for `mastefan`.
+This space runs a full Streamlit app including:
+
+- Audio conversation partner (Qwen + Whisper)
+- OCR → flashcards
+- Flashcard viewer + quizzes
+- User login system (local JSON)

app.py

@@ -0,0 +1,11 @@
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent
+SRC = ROOT / "src"
+sys.path.append(str(SRC))
+
+from app.main_app import main
+
+if __name__ == "__main__":
+    main()

data/auth/users.json

@@ -0,0 +1 @@
+{}

requirements.txt

@@ -0,0 +1,14 @@
+streamlit==1.28.0
+tornado==6.3.3
+deep-translator
+pytesseract
+pillow
+gTTS
+pydub
+soundfile
+transformers==4.40.0
+accelerate
+sentencepiece
+faster-whisper==1.0.3
+ctranslate2==4.5.0
+streamlit-audiorecorder

src/app/__init__.py

@@ -0,0 +1,15 @@
+
+"""
+App package initializer for the Agentic Language Partner project.
+Makes core modules importable and organizes app-wide namespaces.
+"""
+
+__all__ = [
+    "auth",
+    "config",
+    "conversation_core",
+    "flashcards_tools",
+    "ocr_tools",
+    "quiz_tools",
+    "viewers",
+]

src/app/auth.py

@@ -0,0 +1,89 @@
+
+# src/app/auth.py
+
+import json
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+
+from app.config import get_user_dir
+
+
+def _get_users_json() -> Path:
+    """
+    Returns: Path to the main users.json file.
+    """
+    root = Path(__file__).resolve().parents[2]
+    auth_dir = root / "data" / "auth"
+    auth_dir.mkdir(parents=True, exist_ok=True)
+    users_file = auth_dir / "users.json"
+
+    if not users_file.exists():
+        users_file.write_text("{}", encoding="utf-8")
+
+    return users_file
+
+
+def _load_users() -> Dict[str, Dict]:
+    users_file = _get_users_json()
+    try:
+        return json.loads(users_file.read_text(encoding="utf-8"))
+    except Exception:
+        return {}
+
+
+def _save_users(data: Dict[str, Dict]) -> None:
+    users_file = _get_users_json()
+    users_file.write_text(json.dumps(data, indent=2), encoding="utf-8")
+
+
+# ------------------------------------------------------------
+# AUTH FUNCTIONS
+# ------------------------------------------------------------
+
+def register_user(username: str, password: str) -> bool:
+    if not username or not password:
+        return False
+
+    users = _load_users()
+    if username in users:
+        return False
+
+    users[username] = {
+        "password": password,
+        "prefs": {
+            "target_language": "english",
+            "native_language": "english",
+            "cefr_level": "B1",
+            "topic": "general conversation",
+        },
+    }
+    _save_users(users)
+
+    # create the user folder
+    get_user_dir(username)
+
+    return True
+
+
+def authenticate_user(username: str, password: str) -> bool:
+    users = _load_users()
+    entry = users.get(username)
+    if not entry:
+        return False
+    return entry.get("password") == password
+
+
+def get_user_prefs(username: str) -> Dict:
+    users = _load_users()
+    entry = users.get(username, {})
+    return entry.get("prefs", {})
+
+
+def update_user_prefs(username: str, prefs: Dict) -> None:
+    users = _load_users()
+    if username not in users:
+        return
+    users[username]["prefs"] = prefs
+    _save_users(users)
+

src/app/config.py

@@ -0,0 +1,44 @@
+
+# src/app/config.py
+
+from pathlib import Path
+
+
+def get_project_root() -> Path:
+    """
+    Returns the project root directory.
+
+    Assumes this file is located at:
+      <project_root>/src/app/config.py
+    so we go up two parents.
+    """
+    return Path(__file__).resolve().parents[2]
+
+
+def get_data_dir() -> Path:
+    """
+    Root data directory for all persisted user content.
+    """
+    root = get_project_root()
+    data_dir = root / "data"
+    data_dir.mkdir(parents=True, exist_ok=True)
+    return data_dir
+
+
+def get_user_dir(username: str) -> Path:
+    """
+    Returns the directory for a given user and ensures that
+    its subfolders exist.
+    """
+    data_dir = get_data_dir()
+    user_dir = data_dir / "users" / username
+    user_dir.mkdir(parents=True, exist_ok=True)
+
+    # create standard subfolders
+    (user_dir / "decks").mkdir(parents=True, exist_ok=True)
+    (user_dir / "viewers").mkdir(parents=True, exist_ok=True)
+    (user_dir / "chats").mkdir(parents=True, exist_ok=True)
+    (user_dir / "quizzes").mkdir(parents=True, exist_ok=True)
+
+    return user_dir
+

src/app/conversation_core.py

@@ -0,0 +1,357 @@
+
+###############################################################
+# conversation_core.py — Agentic Partner Core (Qwen 1.5B + Whisper)
+###############################################################
+
+import io
+import re
+import tempfile
+from dataclasses import dataclass
+from typing import List, Optional, Tuple
+
+import torch
+from gtts import gTTS
+from faster_whisper import WhisperModel
+from transformers import (
+    AutoTokenizer,
+    AutoModelForCausalLM,
+)
+
+###############################################################
+# MODEL / LANGUAGE CONSTANTS
+###############################################################
+
+QWEN_MODEL_NAME = "Qwen/Qwen2.5-1.5B-Instruct"
+WHISPER_MODEL_SIZE = "base"  # you can change to "large-v3" if GPU budget allows
+
+_QWEN_TOKENIZER = None
+_QWEN_MODEL = None
+_WHISPER = None
+
+# Spoken language -> Whisper hint
+WHISPER_LANG_MAP = {
+    "english": "en",
+    "german": "de",
+    "spanish": "es",
+    "russian": "ru",
+    "french": "fr",
+    "italian": "it",
+    "japanese": "ja",
+    "chinese": "zh",
+    "korean": "ko",
+    "arabic": "ar",
+    "hindi": "hi",
+}
+
+# Spoken language -> gTTS language code
+GTTS_LANG = {
+    "english": "en",
+    "spanish": "es",
+    "german": "de",
+    "russian": "ru",
+    "japanese": "ja",
+    "chinese": "zh-cn",
+    "korean": "ko",
+    "french": "fr",
+    "italian": "it",
+}
+
+CONTROL_PROMPTS = {
+    "A1": "Use extremely short, simple sentences and very basic vocabulary.",
+    "A2": "Use simple sentences and common everyday vocabulary.",
+    "B1": "Use moderately complex sentences and conversational vocabulary.",
+    "B2": "Use natural, fluent sentences with richer vocabulary.",
+    "C1": "Use complex, advanced sentences with nuanced expressions.",
+    "C2": "Use highly sophisticated, near-native language and style.",
+}
+
+
+###############################################################
+# GLOBAL LOADERS
+###############################################################
+
+def load_partner_lm() -> Tuple[AutoTokenizer, AutoModelForCausalLM]:
+    global _QWEN_TOKENIZER, _QWEN_MODEL
+    if _QWEN_TOKENIZER is not None and _QWEN_MODEL is not None:
+        return _QWEN_TOKENIZER, _QWEN_MODEL
+
+    print("[conversation_core] Loading partner LM:", QWEN_MODEL_NAME)
+    tok = AutoTokenizer.from_pretrained(QWEN_MODEL_NAME, trust_remote_code=True)
+    model = AutoModelForCausalLM.from_pretrained(
+        QWEN_MODEL_NAME,
+        torch_dtype=torch.float16 if torch.cuda.is_available() else torch.float32,
+        device_map="auto",
+        trust_remote_code=True,
+    )
+    _QWEN_TOKENIZER = tok
+    _QWEN_MODEL = model
+    return tok, model
+
+
+def load_whisper() -> WhisperModel:
+    global _WHISPER
+    if _WHISPER is not None:
+        return _WHISPER
+
+    device = "cuda" if torch.cuda.is_available() else "cpu"
+    compute_type = "float16" if device == "cuda" else "int8"
+    print(f"[conversation_core] Loading Whisper {WHISPER_MODEL_SIZE} on {device} ({compute_type})")
+    _WHISPER = WhisperModel(WHISPER_MODEL_SIZE, device=device, compute_type=compute_type)
+    return _WHISPER
+
+
+###############################################################
+# DATA STRUCTURE
+###############################################################
+
+@dataclass
+class ConversationTurn:
+    role: str
+    text: str
+
+
+###############################################################
+# CLEANING
+###############################################################
+
+def clean_assistant_reply(text: str) -> str:
+    """Strip meta, identity, and obvious junk from LM output."""
+    if not text:
+        return ""
+
+    # Remove labels
+    text = re.sub(r"(?i)\b(user|assistant|system)\s*:\s*", "", text)
+
+    # Remove numbered / bullet lists (not wanted in casual chat)
+    text = re.sub(r"(?m)^\s*[-•*]\s+.*$", "", text)
+    text = re.sub(r"(?m)^\s*\d+\.\s+.*$", "", text)
+
+    # Remove obvious identity / HR / meta nonsense
+    identity_patterns = [
+        r"(?i)i am (an?|the)? ?(ai|assistant|speaker|model|natural person).*",
+        r"(?i)my name is [A-Za-zäöüÄÖÜß]+.*",
+        r"(?i)i was created.*",
+        r"(?i)human resources manager.*",
+        r"(?i)job description.*",
+        r"(?i)i am a large language model.*",
+    ]
+    for pat in identity_patterns:
+        text = re.sub(pat, "", text)
+
+    # Trim hanging word fragments at the end
+    text = re.sub(r"[A-Za-zÄÖÜäöüß]+$", "", text)
+
+    # Collapse whitespace
+    text = re.sub(r"\s{2,}", " ", text)
+    return text.strip()
+
+
+###############################################################
+# CONVERSATION MANAGER
+###############################################################
+
+class ConversationManager:
+    def __init__(
+        self,
+        target_language: str = "german",
+        native_language: str = "english",
+        cefr_level: str = "B1",
+        topic: str = "general conversation",
+    ):
+        self.target_language = (target_language or "english").strip().lower()
+        self.native_language = (native_language or "english").strip().lower()
+        self.cefr_level = cefr_level or "B1"
+        self.topic = topic or "general conversation"
+        self.history: List[ConversationTurn] = []
+
+        # Warm-load models once per session
+        load_partner_lm()
+        load_whisper()
+
+    ###########################################################
+    # PROMPT + GENERATION
+    ###########################################################
+
+    def _build_system_prompt(self) -> str:
+        base = (
+            f"You are a friendly conversation partner speaking {self.target_language}. "
+            f"Reply ONLY in {self.target_language}. "
+            f"Do NOT explain grammar, vocabulary, or translations unless the user explicitly asks. "
+            f"Do NOT describe what the sentence means, do NOT say 'the sentence translates to...', "
+            f"and do NOT mention that you are explaining anything. "
+            f"Adapt your language to CEFR level {self.cefr_level}. "
+            f"{CONTROL_PROMPTS.get(self.cefr_level, '')} "
+            "Keep your replies natural and conversational, usually 1–3 short sentences. "
+            "Ask exactly ONE natural follow-up question related to what the user said. "
+            "Never end the conversation unless the user explicitly ends it. "
+            "Do NOT say goodbye or conclude unless the user does. "
+            "Never talk about being an AI, model, or assistant. "
+            "Do not mention job descriptions, resumes, or HR responsibilities unless the user clearly asks. "
+        )
+        if self.topic.strip():
+            base += f"The main topic of conversation is: {self.topic.strip()}. "
+        return base
+
+    def _generate_lm(self, user_text: str) -> str:
+        tok, model = load_partner_lm()
+
+        system_prompt = self._build_system_prompt()
+        messages = [
+            {"role": "system", "content": system_prompt},
+            {
+                "role": "user",
+                "content": f"The user (who speaks {self.native_language}) said: {user_text}",
+            },
+        ]
+
+        prompt = tok.apply_chat_template(
+            messages,
+            tokenize=False,
+            add_generation_prompt=True,
+        )
+
+        enc = tok(prompt, return_tensors="pt").to(model.device)
+
+        with torch.no_grad():
+            out = model.generate(
+                **enc,
+                max_new_tokens=160,           # enough space for natural replies
+                temperature=0.8,
+                top_p=0.95,
+                top_k=50,
+                repetition_penalty=1.15,
+                pad_token_id=tok.eos_token_id,
+                do_sample=True,
+            )
+
+        raw = tok.decode(out[0], skip_special_tokens=True).strip()
+
+        # If the user text is echoed, strip it
+        if user_text in raw:
+            raw = raw.split(user_text)[-1].strip()
+
+        # Remove "assistant" label echoes
+        lines = [
+            ln for ln in raw.splitlines()
+            if ln.strip().lower() not in ("assistant", "assistant:")
+        ]
+        raw = "\n".join(lines).strip()
+
+        return clean_assistant_reply(raw)
+
+    ###########################################################
+    # PUBLIC REPLY API
+    ###########################################################
+
+    def reply(self, user_text: str, input_lang: str = "german"):
+        """Generate a reply + explanation + TTS audio."""
+        self.history.append(ConversationTurn("user", user_text))
+
+        assistant_text = self._generate_lm(user_text)
+        self.history.append(ConversationTurn("assistant", assistant_text))
+
+        explanation = self._generate_explanation(assistant_text)
+        audio = self.text_to_speech(assistant_text)
+
+        return {
+            "reply_text": assistant_text,
+            "explanation": explanation,
+            "audio": audio,
+        }
+
+    ###########################################################
+    # SHORT EXPLANATION (EN / native language)
+    ###########################################################
+
+    def _generate_explanation(self, assistant_text: str) -> str:
+        """Return exactly ONE simple native-language sentence, no meta, no logic."""
+        if not assistant_text:
+            return ""
+
+        tok, model = load_partner_lm()
+        prompt = (
+            f"Rewrite the meaning of this {self.target_language} sentence "
+            f"in ONE very short {self.native_language} sentence. "
+            f"Do NOT explain what you are doing, do NOT say 'the sentence means', "
+            f"do NOT describe tone, and do NOT provide multiple versions.\n"
+            f"Sentence: \"{assistant_text}\""
+        )
+
+        enc = tok(prompt, return_tensors="pt").to(model.device)
+        with torch.no_grad():
+            out = model.generate(
+                **enc,
+                max_new_tokens=40,
+                temperature=0.6,
+                top_p=0.9,
+                pad_token_id=tok.eos_token_id,
+            )
+
+        raw = tok.decode(out[0], skip_special_tokens=True)
+        raw = raw.replace(prompt, "").strip()
+
+        # keep first sentence only
+        parts = re.split(r"(?<=[.!?])\s+", raw)
+        if parts:
+            raw = parts[0].strip()
+
+        # remove meta leftovers
+        raw = re.sub(r"(?i)the sentence.*$", "", raw)
+        raw = re.sub(r"(?i)this means.*$", "", raw)
+
+        return raw.strip()
+
+
+
+    ###########################################################
+    # AUDIO TRANSCRIPTION
+    ###########################################################
+
+    def transcribe(self, audio_segment, spoken_lang: str = "english"):
+        """
+        Faster-Whisper transcription with optional language hint.
+        Returns (text, detected_lang_or_hint, dummy_confidence).
+        """
+        whisper = load_whisper()
+
+        lang_key = (spoken_lang or "english").strip().lower()
+        lang_hint = WHISPER_LANG_MAP.get(lang_key)
+
+        with tempfile.NamedTemporaryFile(suffix=".wav", delete=False) as tmp:
+            # Normalize and export pydub AudioSegment
+            audio_segment.set_channels(1).set_frame_rate(16000).export(
+                tmp.name, format="wav"
+            )
+
+            decode_opts = {"beam_size": 5}
+            if lang_hint:
+                decode_opts["language"] = lang_hint
+
+            segments, info = whisper.transcribe(tmp.name, **decode_opts)
+
+        full_text = " ".join(getattr(seg, "text", "") for seg in segments)
+        return full_text.strip(), (lang_hint or "auto"), 1.0
+
+    ###########################################################
+    # TEXT → SPEECH
+    ###########################################################
+
+    def text_to_speech(self, text: str) -> Optional[bytes]:
+        """Return MP3 bytes for the assistant text, or None on failure."""
+        if not text:
+            return None
+        try:
+            lang_code = GTTS_LANG.get(self.target_language, "en")
+            tts = gTTS(text=text, lang=lang_code)
+            buf = io.BytesIO()
+            tts.write_to_fp(buf)
+            return buf.getvalue()
+        except Exception:
+            return None
+
+
+###############################################################
+# END OF FILE
+###############################################################
+
+

src/app/flashcards_tools.py

@@ -0,0 +1,241 @@
+
+# src/app/flashcards_tools.py
+
+import json
+import re
+from pathlib import Path
+from typing import Dict, List, Tuple, Optional
+
+from deep_translator import GoogleTranslator
+
+from app.config import get_user_dir
+
+
+def _get_decks_dir(username: str) -> Path:
+    """
+    Returns the directory where all of a user's decks are stored.
+    """
+    user_dir = get_user_dir(username)
+    decks_dir = user_dir / "decks"
+    decks_dir.mkdir(parents=True, exist_ok=True)
+    return decks_dir
+
+
+def list_user_decks(username: str) -> Dict[str, Path]:
+    """
+    Returns a mapping of deck name -> deck json path.
+    Deck name is taken from the deck's "name" field if present,
+    otherwise the filename stem.
+    """
+    decks_dir = _get_decks_dir(username)
+    deck_files = sorted(decks_dir.glob("*.json"))
+    decks: Dict[str, Path] = {}
+
+    for path in deck_files:
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+            name = data.get("name") or path.stem
+        except Exception:
+            name = path.stem
+
+        # ensure uniqueness by appending stem if needed
+        if name in decks and decks[name] != path:
+            name = f"{name} ({path.stem})"
+        decks[name] = path
+
+    return decks
+
+
+def _ensure_card_stats(card: Dict) -> None:
+    """
+    Ensure that a card has simple spaced-repetition stats.
+    """
+    if "score" not in card:  # learning strength
+        card["score"] = 0
+    if "reviews" not in card:
+        card["reviews"] = 0
+
+
+def load_deck(path: Path) -> Dict:
+    """
+    Loads a deck from JSON, ensuring 'cards' exists and that
+    each card has basic stats for spaced repetition.
+    """
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except Exception:
+        data = {}
+    if "cards" not in data or not isinstance(data["cards"], list):
+        data["cards"] = []
+    if "name" not in data:
+        data["name"] = path.stem
+    if "tags" not in data or not isinstance(data["tags"], list):
+        data["tags"] = []
+
+    for card in data["cards"]:
+        _ensure_card_stats(card)
+
+    return data
+
+
+def save_deck(path: Path, deck: Dict) -> None:
+    """
+    Saves deck to JSON.
+    """
+    if "cards" not in deck:
+        deck["cards"] = []
+    if "name" not in deck:
+        deck["name"] = path.stem
+    if "tags" not in deck or not isinstance(deck["tags"], list):
+        deck["tags"] = []
+
+    # make sure stats are present
+    for card in deck["cards"]:
+        _ensure_card_stats(card)
+
+    path.write_text(json.dumps(deck, indent=2, ensure_ascii=False), encoding="utf-8")
+
+
+# ------------------------------------------------------------
+# Shared tokenization
+# ------------------------------------------------------------
+
+def _extract_candidate_words(text: str) -> List[str]:
+    """
+    Simple tokenizer & filter for candidate vocab words.
+    """
+    tokens = re.findall(r"\b\w+\b", text, flags=re.UNICODE)
+    out = []
+    seen = set()
+    for t in tokens:
+        t_norm = t.strip()
+        if len(t_norm) < 2:
+            continue
+        if any(ch.isdigit() for ch in t_norm):
+            continue
+        lower = t_norm.lower()
+        if lower in seen:
+            continue
+        seen.add(lower)
+        out.append(t_norm)
+    return out
+
+
+# ------------------------------------------------------------
+# OCR → Flashcards
+# ------------------------------------------------------------
+
+def generate_flashcards_from_ocr_results(
+    username: str,
+    ocr_results: List[Dict],
+    deck_name: str = "ocr",
+    target_lang: str = "en",
+    tags: Optional[List[str]] = None,
+) -> Path:
+    """
+    Takes OCR results (as produced by ocr_tools.ocr_and_translate_batch)
+    and constructs a simple vocab deck.
+
+    ocr_results: list of dict with keys:
+        - "text": original text
+        - optionally other fields (ignored)
+    """
+    all_text = []
+    for res in ocr_results:
+        t = res.get("text") or res.get("raw_text") or ""
+        if t:
+            all_text.append(t)
+    joined = "\n".join(all_text)
+
+    words = _extract_candidate_words(joined)
+    if not words:
+        raise ValueError("No candidate words found in OCR results.")
+
+    translator = GoogleTranslator(source="auto", target=target_lang)
+    cards = []
+    for w in words:
+        try:
+            trans = translator.translate(w)
+        except Exception:
+            continue
+        if not trans:
+            continue
+        if trans.strip().lower() == w.strip().lower():
+            continue
+        card = {
+            "front": w,
+            "back": trans,
+            "content_type": "ocr_vocab",
+            "language": target_lang,
+        }
+        _ensure_card_stats(card)
+        cards.append(card)
+
+    if not cards:
+        raise ValueError("No translatable words found to build cards.")
+
+    decks_dir = _get_decks_dir(username)
+    deck_path = decks_dir / f"{deck_name}.json"
+
+    deck = {
+        "name": deck_name,
+        "cards": cards,
+        "tags": tags or [],
+    }
+    save_deck(deck_path, deck)
+    return deck_path
+
+
+# ------------------------------------------------------------
+# Conversation/Text → Flashcards
+# ------------------------------------------------------------
+
+def generate_flashcards_from_text(
+    username: str,
+    text: str,
+    deck_name: str = "conversation",
+    target_lang: str = "en",
+    tags: Optional[List[str]] = None,
+) -> Path:
+    """
+    Build a vocab deck from raw conversation text.
+    """
+    words = _extract_candidate_words(text)
+    if not words:
+        raise ValueError("No candidate words found in text.")
+
+    translator = GoogleTranslator(source="auto", target=target_lang)
+    cards = []
+    for w in words:
+        try:
+            trans = translator.translate(w)
+        except Exception:
+            continue
+        if not trans:
+            continue
+        if trans.strip().lower() == w.strip().lower():
+            continue
+        card = {
+            "front": w,
+            "back": trans,
+            "content_type": "conversation_vocab",
+            "language": target_lang,
+        }
+        _ensure_card_stats(card)
+        cards.append(card)
+
+    if not cards:
+        raise ValueError("No translatable words found to build cards.")
+
+    decks_dir = _get_decks_dir(username)
+    deck_path = decks_dir / f"{deck_name}.json"
+
+    deck = {
+        "name": deck_name,
+        "cards": cards,
+        "tags": tags or ["conversation"],
+    }
+    save_deck(deck_path, deck)
+    return deck_path
+
+

src/app/main_app.py

@@ -0,0 +1,1235 @@
+
+###############################################################
+# main_app.py — Agentic Language Partner UI (Streamlit)
+###############################################################
+import pandas as pd
+import json
+import random
+import re
+from datetime import datetime
+from pathlib import Path
+from typing import Dict, List, Any
+
+import streamlit as st
+import streamlit.components.v1 as components
+from audiorecorder import audiorecorder
+from deep_translator import GoogleTranslator
+
+from app.auth import (
+    authenticate_user,
+    register_user,
+    get_user_prefs,
+    update_user_prefs,
+)
+from app.config import get_user_dir
+from app.conversation_core import ConversationManager
+from app.flashcards_tools import (
+    list_user_decks,
+    load_deck,
+    _get_decks_dir,
+    save_deck,
+    generate_flashcards_from_text,
+    generate_flashcards_from_ocr_results,
+)
+from app.ocr_tools import ocr_and_translate_batch
+from app.viewers import generate_flashcard_viewer_for_user
+
+
+###############################################################
+# PAGE + GLOBAL STYLE
+###############################################################
+
+st.set_page_config(
+    page_title="Agentic Language Partner",
+    layout="wide",
+    page_icon="🌐",
+)
+
+st.markdown(
+    """
+<style>
+
+.chat-column {
+    display: flex;
+    flex-direction: column;
+}
+
+
+
+/* Input bar at the top */
+.chat-input-bar {
+    margin-bottom: 0.5rem;
+    background-color: #111;
+    padding: 0.75rem 0.5rem 0.5rem;
+    border: 1px solid #333;
+    border-radius: 0.5rem;
+}
+
+/* Scrollable chat messages below input */
+.chat-window {
+    max-height: 65vh;
+    overflow-y: auto;
+    padding-right: .75rem;
+    padding-bottom: 0.5rem;
+}
+
+/* Chat bubbles */
+.chat-row-user { justify-content:flex-end; display:flex; margin-bottom:.4rem; }
+.chat-row-assistant { justify-content:flex-start; display:flex; margin-bottom:.4rem; }
+
+.chat-bubble {
+    border-radius:14px;
+    padding:.55rem .95rem;
+    max-width:80%;
+    line-height:1.4;
+    box-shadow:0 2px 5px rgba(0,0,0,0.4);
+    font-size:1.05rem;  /* larger for readability */
+}
+.chat-bubble-user { background:#3a3b3c; color:white; }
+.chat-bubble-assistant { background:#1a73e8; color:white; }
+
+.chat-aux {
+    font-size:1.0rem;   /* larger translation/explanation */
+    color:#ccc;
+    margin:0.1rem 0.25rem 0.5rem 0.25rem;
+}
+
+/* Lock viewport height and avoid infinite page scrolling */
+html, body {
+    height: 100%;
+    overflow: hidden !important;
+}
+
+.block-container {
+    height: 100vh !important;
+    overflow-y: auto !important;
+}
+
+.saved-conv-panel { max-width: 360px; }
+
+</style>
+""",
+    unsafe_allow_html=True,
+)
+
+
+###############################################################
+# HELPERS / GLOBALS
+###############################################################
+# ------------------------------------------------------------
+# Model preload / Conversation manager
+# ------------------------------------------------------------
+
+def preload_models():
+    """
+    Preloads Whisper, Qwen, and NLLB models only one time.
+    This prevents UI freeze or repeated loading during conversation.
+    """
+    if st.session_state.get("models_loaded"):
+        return
+
+    with st.spinner("Loading language & speech models (one-time)…"):
+        try:
+            load_whisper()
+        except Exception:
+            pass
+        try:
+            load_partner_lm()
+        except Exception:
+            pass
+        try:
+            load_nllb()
+        except Exception:
+            pass
+
+    st.session_state["models_loaded"] = True
+
+
+
+def get_conv_manager() -> ConversationManager:
+    if "conv_manager" not in st.session_state:
+        prefs = st.session_state["prefs"]
+        st.session_state["conv_manager"] = ConversationManager(
+            target_language=prefs.get("target_language", "english"),
+            native_language=prefs.get("native_language", "english"),
+            cefr_level=prefs.get("cefr_level", "B1"),
+            topic=prefs.get("topic", "general conversation"),
+        )
+    return st.session_state["conv_manager"]
+
+
+def ensure_default_decks(username: str):
+    decks_dir = _get_decks_dir(username)
+
+    alpha = decks_dir / "alphabet.json"
+    if not alpha.exists():
+        save_deck(alpha, {
+            "name": "Alphabet (A–Z)",
+            "cards": [{"front": chr(65+i), "back": f"Letter {chr(65+i)}"} for i in range(26)],
+            "tags": ["starter"],
+        })
+
+    nums = decks_dir / "numbers_1_10.json"
+    if not nums.exists():
+        save_deck(nums, {
+            "name": "Numbers 1–10",
+            "cards": [{"front": str(i), "back": f"Number {i}"} for i in range(1, 11)],
+            "tags": ["starter"],
+        })
+
+    greetings = decks_dir / "greetings_intros.json"
+    if not greetings.exists():
+        save_deck(greetings, {
+            "name": "Greetings & Introductions",
+            "cards": [
+                {"front": "Hallo!", "back": "Hello!"},
+                {"front": "Wie geht's?", "back": "How are you?"},
+                {"front": "Ich heiße …", "back": "My name is …"},
+                {"front": "Freut mich!", "back": "Nice to meet you!"},
+            ],
+            "tags": ["starter"],
+        })
+
+
+def ui_clean_assistant_text(text: str) -> str:
+    if not text:
+        return ""
+    text = re.sub(r"(?i)\b(user|assistant|system):\s*", "", text)
+    text = re.sub(r"\s{2,}", " ", text)
+    return text.strip()
+
+
+def save_current_conversation(username: str, name: str) -> Path:
+    """Save chat_history as JSON, stripping non-serializable fields (audio bytes)."""
+    user_dir = get_user_dir(username)
+    save_dir = user_dir / "chats" / "saved"
+    save_dir.mkdir(parents=True, exist_ok=True)
+
+    cleaned_messages = []
+    for m in st.session_state.get("chat_history", []):
+        cleaned_messages.append(
+            {
+                "role": m.get("role"),
+                "text": m.get("text"),
+                "explanation": m.get("explanation"),
+                # store only a flag for audio, not raw bytes
+                "audio_present": bool(m.get("audio")),
+            }
+        )
+
+    payload = {
+        "name": name,
+        "timestamp": datetime.utcnow().isoformat(),
+        "messages": cleaned_messages,
+    }
+    fname = datetime.utcnow().strftime("%Y%m%d_%H%M%S") + ".json"
+    path = save_dir / fname
+    path.write_text(json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8")
+    return path
+
+
+
+###############################################################
+# CHAT HANDLING
+###############################################################
+
+def handle_user_message(username: str, text: str):
+    text = text.strip()
+    if not text:
+        return
+
+    conv = get_conv_manager()
+
+    st.session_state["chat_history"].append(
+        {"role": "user", "text": text, "audio": None, "explanation": None}
+    )
+
+    with st.spinner("Thinking…"):
+        result = conv.reply(text)
+
+    reply_text = ui_clean_assistant_text(result.get("reply_text", ""))
+    reply_audio = result.get("audio", None)
+    explanation = ui_clean_assistant_text(result.get("explanation", ""))
+
+    st.session_state["chat_history"].append(
+        {
+            "role": "assistant",
+            "text": reply_text,
+            "audio": reply_audio,
+            "explanation": explanation,
+        }
+    )
+
+
+###############################################################
+# AUTH
+###############################################################
+
+def login_view():
+    st.title("🌐 Agentic Language Partner")
+    tab1, tab2 = st.tabs(["Login", "Register"])
+
+    with tab1:
+        u = st.text_input("Username")
+        p = st.text_input("Password", type="password")
+        if st.button("Login"):
+            if authenticate_user(u, p):
+                st.session_state["user"] = u
+                st.session_state["prefs"] = get_user_prefs(u)
+                st.experimental_rerun()
+            else:
+                st.error("Invalid login.")
+
+    with tab2:
+        u = st.text_input("New username")
+        p = st.text_input("New password", type="password")
+        if st.button("Register"):
+            if register_user(u, p):
+                st.success("Registered! Please log in.")
+            else:
+                st.error("Username already exists.")
+
+
+###############################################################
+# SIDEBAR SETTINGS
+###############################################################
+
+def sidebar_settings(username: str):
+    st.sidebar.header("⚙ Settings")
+
+    prefs = st.session_state["prefs"]
+    langs = ["english", "spanish", "german", "russian", "japanese", "chinese", "korean"]
+
+    tgt = st.sidebar.selectbox(
+        "Target language",
+        langs,
+        index=langs.index(prefs.get("target_language", "english")),
+        key="sidebar_target",
+    )
+    nat = st.sidebar.selectbox(
+        "Native language",
+        langs,
+        index=langs.index(prefs.get("native_language", "english")),
+        key="sidebar_native",
+    )
+
+    cefr_levels = ["A1", "A2", "B1", "B2", "C1", "C2"]
+    level = st.sidebar.selectbox(
+        "CEFR Level",
+        cefr_levels,
+        index=cefr_levels.index(prefs.get("cefr_level", "B1")),
+        key="sidebar_cefr",
+    )
+
+    topic = st.sidebar.text_input(
+        "Conversation Topic",
+        prefs.get("topic", "general conversation"),
+        key="sidebar_topic",
+    )
+
+    show_exp = st.sidebar.checkbox(
+        "Show Explanations",
+        value=prefs.get("show_explanations", True),
+        key="sidebar_show_exp",
+    )
+
+    if st.sidebar.button("Save Settings"):
+        new = {
+            "target_language": tgt,
+            "native_language": nat,
+            "cefr_level": level,
+            "topic": topic,
+            "show_explanations": show_exp,
+        }
+        st.session_state["prefs"] = new
+        update_user_prefs(username, new)
+        if "conv_manager" in st.session_state:
+            del st.session_state["conv_manager"]
+        st.sidebar.success("Settings saved!")
+
+
+###############################################################
+# DASHBOARD TAB
+###############################################################
+
+def dashboard_tab(username: str):
+    st.title("Agentic Language Partner — Dashboard")
+
+    prefs = st.session_state["prefs"]
+    langs = ["english", "spanish", "german", "russian", "japanese", "chinese", "korean"]
+
+    st.subheader("Language Settings")
+
+    col1, col2, col3 = st.columns(3)
+
+    with col1:
+        native = st.selectbox(
+            "Native language",
+            langs,
+            index=langs.index(prefs.get("native_language", "english")),
+            key="dash_native_language",
+        )
+    with col2:
+        target = st.selectbox(
+            "Target language",
+            langs,
+            index=langs.index(prefs.get("target_language", "english")),
+            key="dash_target_language",
+        )
+    with col3:
+        cefr_levels = ["A1", "A2", "B1", "B2", "C1", "C2"]
+        level = st.selectbox(
+            "CEFR Level",
+            cefr_levels,
+            index=cefr_levels.index(prefs.get("cefr_level", "B1")),
+            key="dash_cefr_level",
+        )
+
+    topic = st.text_input(
+        "Conversation Topic",
+        prefs.get("topic", "general conversation"),
+        key="dash_topic",
+    )
+
+    if st.button("Save Language Settings", key="dash_save_lang"):
+        new = {
+            "native_language": native,
+            "target_language": target,
+            "cefr_level": level,
+            "topic": topic,
+            "show_explanations": prefs.get("show_explanations", True),
+        }
+        st.session_state["prefs"] = new
+        update_user_prefs(username, new)
+        if "conv_manager" in st.session_state:
+            del st.session_state["conv_manager"]
+        st.success("Language settings saved!")
+
+    st.markdown("---")
+
+    ###########################################################
+    # MICROPHONE & TRANSCRIPTION CALIBRATION (native phrase)
+    ###########################################################
+    # ---- Microphone & transcription calibration (restored original version) ----
+    st.subheader("Microphone & Transcription Calibration")
+
+    st.write(
+        "To verify that audio recording and transcription are working, "
+        "please repeat this phrase in your native language:\n\n"
+        "> \"Hello, my name is [Your Name], and I am here to practice languages.\"\n\n"
+        "Record a short clip and then run transcription to check accuracy."
+    )
+
+    calib_col1, calib_col2 = st.columns([2, 1])
+
+    with calib_col1:
+        calib_audio = audiorecorder(
+            "🎤 Start calibration",
+            "⏹ Stop",
+            key="calibration_audio",
+        )
+
+        if len(calib_audio) > 0:
+            st.caption("Calibration audio recorded. Click 'Transcribe sample' to test.")
+
+        if st.button("Transcribe sample", key="calibration_transcribe"):
+            if len(calib_audio) == 0:
+                st.warning("Please record a short calibration clip first.")
+            else:
+                conv = get_conv_manager()
+                try:
+                    seg = calib_audio.set_frame_rate(16000).set_channels(1)
+                    with st.spinner("Transcribing calibration audio…"):
+                        text_out, det_lang, det_prob = conv.transcribe(
+                            seg,
+                            spoken_lang=st.session_state["prefs"]["native_language"]
+                        )
+                    st.session_state["calibration_result"] = {
+                        "text": text_out,
+                        "det_lang": det_lang,
+                        "det_prob": det_prob,
+                    }
+                    st.success("Calibration transcript updated.")
+                except Exception as e:
+                    st.error(f"Calibration error: {e}")
+
+    with calib_col2:
+        if st.session_state.get("calibration_result"):
+            res = st.session_state["calibration_result"]
+            st.markdown("**Calibration transcript:**")
+            st.info(res.get("text", ""))
+            st.caption(
+                f"Detected lang: {res.get('det_lang','?')} · Confidence ~ {res.get('det_prob', 0):.2f}"
+            )
+        else:
+            st.caption("No calibration transcript yet.")
+
+    st.markdown("---")
+
+
+
+
+    ###########################################################
+    # TOOL OVERVIEW
+    ###########################################################
+    st.subheader("Tools Overview")
+
+    c1, c2, c3 = st.columns(3)
+    with c1:
+        st.markdown("### 🎙️ Conversation Partner")
+        st.write("Real-time language practice with microphone support.")
+
+    with c2:
+        st.markdown("### 🃏 Flashcards & Quizzes")
+        st.write("Starter decks: Alphabet, Numbers, Greetings.")
+
+    with c3:
+        st.markdown("### 📷 OCR Helper")
+        st.write("Upload images to extract and translate text.")
+
+# ------------------------------------------------------------
+# Settings tab  (restore missing function)
+# ------------------------------------------------------------
+def settings_tab(username: str):
+    """Minimal settings tab so main() can call it safely."""
+    st.header("Settings")
+
+    st.subheader("User Preferences")
+    prefs = st.session_state.get("prefs", {})
+    st.json(prefs)
+
+    st.markdown("---")
+
+    st.subheader("System Status")
+    st.write("Models preloaded:", st.session_state.get("models_loaded", False))
+
+    st.markdown(
+        "This is a placeholder settings panel. "
+        "You can customize this later with user-specific configuration."
+    )
+
+
+
+###############################################################
+# CONVERSATION TAB
+###############################################################
+
+def conversation_tab(username: str):
+    import re
+    from datetime import datetime
+    from deep_translator import GoogleTranslator
+
+    st.header("Conversation")
+
+    # ------------------------------------------
+    # INITIAL STATE
+    # ------------------------------------------
+    if "chat_history" not in st.session_state:
+        st.session_state["chat_history"] = []
+
+    if "pending_transcript" not in st.session_state:
+        st.session_state["pending_transcript"] = ""
+
+    if "speech_state" not in st.session_state:
+        st.session_state["speech_state"] = "idle"   # idle | pending_speech
+
+    if "recorder_key" not in st.session_state:
+        st.session_state["recorder_key"] = 0
+
+    conv = get_conv_manager()
+    prefs = st.session_state.get("prefs", {})
+    show_exp = prefs.get("show_explanations", True)
+
+    # ------------------------------------------
+    # RESET BUTTON (ONLY ONE)
+    # ------------------------------------------
+    if st.button("🔄 Reset Conversation"):
+        st.session_state["chat_history"] = []
+        st.session_state["pending_transcript"] = ""
+        st.session_state["speech_state"] = "idle"
+        st.session_state["recorder_key"] += 1
+        st.experimental_rerun()
+
+
+    # ------------------------------------------
+    # FIRST MESSAGE GREETING
+    # ------------------------------------------
+    if len(st.session_state["chat_history"]) == 0:
+        lang = conv.target_language.lower()
+        topic = prefs.get("topic", "").strip()
+
+        default_greetings = {
+            "english": "Hello! I heard you want to practice with me. How is your day going?",
+            "german":  "Hallo! Ich habe gehört, dass du üben möchtest. Wie geht dein Tag bisher?",
+            "spanish": "¡Hola! Escuché que querías practicar conmigo. ¿Cómo va tu día?",
+            "japanese":"こんにちは！練習したいと聞きました。今日はどんな一日ですか？",
+        }
+
+        intro = default_greetings.get(lang, default_greetings["english"])
+
+        if topic and topic.lower() != "general conversation":
+            try:
+                intro = GoogleTranslator(source="en", target=lang).translate(
+                    f"Hello! Let's talk about {topic}. What do you think about it?"
+                )
+            except Exception:
+                pass
+
+        st.session_state["chat_history"].append(
+            {"role":"assistant","text":intro,"audio":None,"explanation":None}
+        )
+
+    # ------------------------------------------
+    # LAYOUT
+    # ------------------------------------------
+    col_chat, col_saved = st.columns([3,1])
+
+    # ===========================
+    # LEFT: CHAT WINDOW
+    # ===========================
+    with col_chat:
+
+        st.markdown('<div class="chat-window">', unsafe_allow_html=True)
+
+        for msg in st.session_state["chat_history"]:
+            role = msg["role"]
+            bubble = "chat-bubble-user" if role == "user" else "chat-bubble-assistant"
+            row    = "chat-row-user"     if role == "user" else "chat-row-assistant"
+
+            st.markdown(
+                f'<div class="{row}"><div class="chat-bubble {bubble}">{msg["text"]}</div></div>',
+                unsafe_allow_html=True,
+            )
+
+            if role == "assistant" and msg.get("audio"):
+                st.audio(msg["audio"], format="audio/mp3")
+
+            if role == "assistant":
+                try:
+                    tr = GoogleTranslator(source="auto", target=conv.native_language).translate(msg["text"])
+                    st.markdown(f'<div class="chat-aux">{tr}</div>', unsafe_allow_html=True)
+                except: pass
+
+                if show_exp and msg.get("explanation"):
+                    exp = msg["explanation"]
+
+                    # Force EXACTLY ONE sentence
+                    exp = re.split(r"(?<=[.!?])\s+", exp)[0].strip()
+
+                    # Remove any meta nonsense ("version:", "meaning:", "this sentence", etc)
+                    exp = re.sub(r"(?i)(english version|the meaning|this sentence|the german sentence).*", "", exp).strip()
+
+                    if exp:
+                        st.markdown(f'<div class="chat-aux">{exp}</div>', unsafe_allow_html=True)
+
+        # scroll
+        st.markdown("""
+            <script>
+            setTimeout(() => {
+                let w = window.parent.document.getElementsByClassName('chat-window')[0];
+                if (w) w.scrollTop = w.scrollHeight;
+            }, 200);
+            </script>
+        """, unsafe_allow_html=True)
+
+        # -------------------------------
+        # AUDIO RECORDER
+        # -------------------------------
+        st.markdown('<div class="sticky-input-bar">', unsafe_allow_html=True)
+
+        audio = audiorecorder("🎤 Speak", "⏹ Stop",
+                              key=f"chat_audio_{st.session_state['recorder_key']}")
+
+        # ------------------------------------------
+        # STATE: idle → record → transcribe
+        # ------------------------------------------
+        if st.session_state["speech_state"] == "idle":
+            if audio and len(audio) > 0:
+                seg = audio.set_frame_rate(16000).set_channels(1)
+                with st.spinner("Transcribing…"):
+                    txt, lang, conf = conv.transcribe(seg, spoken_lang=conv.target_language)
+
+                st.session_state["pending_transcript"] = txt.strip()
+                st.session_state["speech_state"] = "pending_speech"
+                st.session_state["recorder_key"] += 1
+                st.experimental_rerun()
+
+        # ------------------------------------------
+        # STATE: pending_speech → confirm
+        # ------------------------------------------
+        if st.session_state["speech_state"] == "pending_speech":
+
+            st.write("### Confirm your spoken message:")
+            st.info(st.session_state["pending_transcript"])
+
+            c1, c2 = st.columns([1,1])
+            with c1:
+                if st.button("Send message", key="send_pending"):
+                    txt = st.session_state["pending_transcript"]
+
+                    with st.spinner("Partner is responding…"):
+                        handle_user_message(username, txt)
+
+                    # cleanup
+                    st.session_state["speech_state"] = "idle"
+                    st.session_state["pending_transcript"] = ""
+                    st.session_state["recorder_key"] += 1
+                    st.experimental_rerun()
+
+            with c2:
+                if st.button("Discard", key="discard_pending"):
+                    st.session_state["speech_state"] = "idle"
+                    st.session_state["pending_transcript"] = ""
+                    st.session_state["recorder_key"] += 1
+                    st.experimental_rerun()
+
+        # -------------------------------
+        # TYPED TEXT INPUT
+        # -------------------------------
+        typed = st.text_input("Type your message:", key="typed_input")
+        if typed.strip() and st.button("Send typed message"):
+            handle_user_message(username, typed.strip())
+            st.session_state["typed_input"] = ""
+            st.experimental_rerun()
+
+        st.markdown("</div>", unsafe_allow_html=True)
+
+        # ======================================================
+        # RIGHT: SAVED CONVERSATIONS (RESTORED)
+        # ======================================================
+        with col_saved:
+            from pathlib import Path
+            import json
+
+            st.markdown("### Saved Conversations")
+
+            default_name = datetime.utcnow().strftime("Session %Y-%m-%d %H:%M")
+            name_box = st.text_input("Name conversation", value=default_name)
+
+            if st.button("Save conversation"):
+                if not st.session_state["chat_history"]:
+                    st.warning("Nothing to save.")
+                else:
+                    safe = re.sub(r"[^0-9A-Za-z_-]", "_", name_box)
+
+                    path = save_current_conversation(username, safe)
+                    st.success(f"Saved as {path.name}")
+
+            saved_dir = get_user_dir(username) / "chats" / "saved"
+            saved_dir.mkdir(parents=True, exist_ok=True)
+
+            files = sorted(saved_dir.glob("*.json"), key=lambda p: p.stat().st_mtime, reverse=True)
+
+            for f in files:
+                data = json.loads(f.read_text())
+                sess_name = data.get("name", f.stem)
+                msgs = data.get("messages", [])
+
+                with st.expander(f"{sess_name} ({len(msgs)} msgs)"):
+                    deck_name = st.text_input(f"Deck name for {sess_name}", value=f"deck_{f.stem}")
+
+                    if st.button(f"Export {f.stem}", key=f"export_{f.stem}"):
+                        body = "\n".join(m["text"] for m in msgs if m["role"] == "assistant")
+                        deck_path = generate_flashcards_from_text(
+                            username=username,
+                            text=body,
+                            deck_name=deck_name,
+                            target_lang=prefs["native_language"],
+                            tags=["conversation"],
+                        )
+                        st.success(f"Deck exported: {deck_path.name}")
+
+                    if st.button(f"Delete {f.stem}", key=f"delete_{f.stem}"):
+                        f.unlink()
+                        st.experimental_rerun()
+
+###############################################################
+# OCR TAB
+###############################################################
+
+def ocr_tab(username: str):
+    st.header("OCR → Flashcards")
+
+    imgs = st.file_uploader("Upload images", ["png", "jpg", "jpeg"], accept_multiple_files=True)
+    tgt = st.selectbox("Translate to", ["en", "de", "ja", "zh-cn", "es"])
+    deck_name = st.text_input("Deck name", "ocr_vocab")
+
+    if st.button("Create Deck from OCR"):
+        if not imgs:
+            st.warning("Upload at least one image.")
+            return
+
+        with st.spinner("Running OCR…"):
+            results = ocr_and_translate_batch([f.read() for f in imgs], target_lang=tgt)
+
+        deck_path = generate_flashcards_from_ocr_results(
+            username=username,
+            ocr_results=results,
+            deck_name=deck_name,
+            target_lang=tgt,
+            tags=["ocr"],
+        )
+        st.success(f"Deck saved: {deck_path}")
+
+
+###############################################################
+# FLASHCARDS TAB
+###############################################################
+
+def flashcards_tab(username: str):
+    import pandas as pd
+    import re
+
+    # ---------------------------------------------------------
+    # Helpers
+    # ---------------------------------------------------------
+
+    def normalize(s: str) -> str:
+        """lowercase + strip non-alphanumerics for loose grading."""
+        s = s.lower()
+        s = re.sub(r"[^a-z0-9]+", "", s)
+        return s
+
+    def card_front_html(text: str) -> str:
+        return f"""
+        <div style="
+            background:#1a73e8;
+            color:white;
+            border-radius:18px;
+            padding:50px;
+            font-size:2.2rem;
+            text-align:center;
+            width:70%;
+            margin-left:auto;
+            margin-right:auto;
+            box-shadow:0 4px 12px rgba(0,0,0,0.3);
+            ">
+            {text}
+        </div>
+        """
+
+    def card_back_html(front: str, back: str) -> str:
+        return f"""
+        <div style="margin-bottom:20px;">
+            <div style="
+                background:#1a73e8;
+                color:white;
+                border-radius:18px;
+                padding:35px;
+                font-size:1.8rem;
+                text-align:center;
+                width:70%;
+                margin-left:auto;
+                margin-right:auto;
+                box-shadow:0 4px 12px rgba(0,0,0,0.25);
+            ">{front}</div>
+
+            <div style="
+                background:#2b2b2b;
+                color:#f5f5f5;
+                border-radius:18px;
+                padding:40px;
+                margin-top:18px;
+                font-size:2rem;
+                text-align:center;
+                width:70%;
+                margin-left:auto;
+                margin-right:auto;
+                box-shadow:0 4px 12px rgba(0,0,0,0.25);
+            ">{back}</div>
+        </div>
+        """
+
+    # ---------------------------------------------------------
+    # Load deck
+    # ---------------------------------------------------------
+
+    st.header("Flashcards")
+
+    decks = list_user_decks(username)
+    if not decks:
+        st.info("No decks available yet.")
+        return
+
+    deck_name = st.selectbox("Select deck", sorted(decks.keys()))
+    deck_path = decks[deck_name]
+    deck = load_deck(deck_path)
+    cards = deck.get("cards", [])
+    tags = deck.get("tags", [])
+
+    if not cards:
+        st.warning("Deck is empty.")
+        return
+
+    st.write(f"Total cards: **{len(cards)}**")
+    if tags:
+        st.caption("Tags: " + ", ".join(tags))
+
+    # Delete deck button
+    if st.button("Delete deck"):
+        deck_path.unlink()
+        st.experimental_rerun()
+
+    # ---------------------------------------------------------
+    # Session state setup
+    # ---------------------------------------------------------
+
+    key = f"fc_{deck_name}_"
+    ss = st.session_state
+
+    if key + "init" not in ss:
+        ss[key + "mode"] = "Study"
+        ss[key + "idx"] = 0
+        ss[key + "show_back"] = False
+
+        # test state
+        ss[key + "test_active"] = False
+        ss[key + "test_order"] = []
+        ss[key + "test_pos"] = 0
+        ss[key + "test_results"] = []
+
+        ss[key + "init"] = True
+
+    conv = get_conv_manager()
+
+    mode = st.radio("Mode", ["Study", "Test"], horizontal=True, key=key + "mode")
+
+    st.markdown("---")
+
+    # =======================================================
+    # CENTER PANEL
+    # =======================================================
+    with st.container():
+
+        # ---------------------------------------------------
+        # STUDY MODE
+        # ---------------------------------------------------
+        if mode == "Study":
+            idx = ss[key + "idx"] % len(cards)
+            card = cards[idx]
+            show_back = ss[key + "show_back"]
+
+            st.markdown("### Study Mode")
+            st.markdown("---")
+
+            # CARD DISPLAY
+            if not show_back:
+                st.markdown(card_front_html(card["front"]), unsafe_allow_html=True)
+                if st.button("🔊 Pronounce", key=key + f"tts_front_{idx}"):
+                    audio = conv.text_to_speech(card["front"])
+                    if audio:
+                        st.audio(audio, format="audio/mp3")
+            else:
+                st.markdown(card_back_html(card["front"], card["back"]), unsafe_allow_html=True)
+                if st.button("🔊 Pronounce", key=key + f"tts_back_{idx}"):
+                    audio = conv.text_to_speech(card["back"])
+                    if audio:
+                        st.audio(audio, format="audio/mp3")
+
+            # FLIPBOOK CONTROLS
+            st.markdown("---")
+            c1, c2, c3 = st.columns(3)
+            with c1:
+                if st.button("Flip", key=key + "flip"):
+                    ss[key + "show_back"] = not show_back
+                    st.experimental_rerun()
+            with c2:
+                if st.button("Shuffle deck", key=key + "shuf"):
+                    random.shuffle(cards)
+                    deck["cards"] = cards
+                    save_deck(deck_path, deck)
+                    ss[key + "idx"] = 0
+                    ss[key + "show_back"] = False
+                    st.experimental_rerun()
+            with c3:
+                if st.button("Next →", key=key + "next"):
+                    ss[key + "idx"] = (idx + 1) % len(cards)
+                    ss[key + "show_back"] = False
+                    st.experimental_rerun()
+
+            # DIFFICULTY GRADING (centered)
+            st.markdown("### Rate this card")
+            cA, cB, cC, cD, cE = st.columns(5)
+
+            def apply_grade(delta):
+                card["score"] = max(0, card.get("score", 0) + delta)
+                card["reviews"] = card.get("reviews", 0) + 1
+                save_deck(deck_path, deck)
+                ss[key + "idx"] = _choose_next_card_index(cards)
+                ss[key + "show_back"] = False
+                st.experimental_rerun()
+
+            with cA:
+                if st.button("🔥 Very Difficult", key=key+"g_vd"):
+                    apply_grade(-2)
+            with cB:
+                if st.button("😣 Hard", key=key+"g_h"):
+                    apply_grade(-1)
+            with cC:
+                if st.button("😐 Neutral", key=key+"g_n"):
+                    apply_grade(0)
+            with cD:
+                if st.button("🙂 Easy", key=key+"g_e"):
+                    apply_grade(1)
+            with cE:
+                if st.button("🏆 Mastered", key=key+"g_m"):
+                    apply_grade(3)
+
+        # ---------------------------------------------------
+        # TEST MODE
+        # ---------------------------------------------------
+        else:
+            # Initial test setup
+            if not ss[key + "test_active"]:
+                st.markdown("### Test Setup")
+                num_q = st.slider("Number of questions", 3, min(20, len(cards)), min(5, len(cards)), key=key+"nq")
+
+                if st.button("Start Test", key=key+"begin"):
+                    order = list(range(len(cards)))
+                    random.shuffle(order)
+                    order = order[:num_q]
+
+                    ss[key + "test_active"] = True
+                    ss[key + "test_order"] = order
+                    ss[key + "test_pos"] = 0
+                    ss[key + "test_results"] = []
+                    st.experimental_rerun()
+
+            else:
+                order = ss[key + "test_order"]
+                pos = ss[key + "test_pos"]
+                results = ss[key + "test_results"]
+
+                # Test Complete
+                if pos >= len(order):
+                    correct = sum(r["correct"] for r in results)
+                    st.markdown(f"### Test Complete — Score: {correct}/{len(results)} ({correct/len(results)*100:.1f}%)")
+                    st.markdown("---")
+
+                    for i, r in enumerate(results, 1):
+                        emoji = "✅" if r["correct"] else "❌"
+                        st.write(f"**{i}.** {r['front']} → expected **{r['back']}**, you answered *{r['user_answer']}* {emoji}")
+
+                    if st.button("Restart Test", key=key+"restart"):
+                        ss[key + "test_active"] = False
+                        ss[key + "test_pos"] = 0
+                        ss[key + "test_results"] = []
+                        ss[key + "test_order"] = []
+                        st.experimental_rerun()
+                    return
+
+                # Current question
+                cid = order[pos]
+                card = cards[cid]
+
+                st.progress(pos / len(order))
+                st.caption(f"Question {pos+1} / {len(order)}")
+
+                st.markdown(card_front_html(card["front"]), unsafe_allow_html=True)
+
+                # TTS
+                if st.button("🔊 Pronounce", key=key+f"tts_test_{pos}"):
+                    audio = conv.text_to_speech(card["front"])
+                    if audio:
+                        st.audio(audio, format="audio/mp3")
+
+                user_answer = st.text_input("Your answer:", key=key+f"ans_{pos}")
+
+                if st.button("Submit Answer", key=key+f"submit_{pos}"):
+                    ua = user_answer.strip()
+                    correct = normalize(ua) == normalize(card["back"])
+
+                    # Flash feedback
+                    if correct:
+                        st.success("Correct!")
+                    else:
+                        st.error(f"Incorrect — expected: {card['back']}")
+
+                    results.append({
+                        "front": card["front"],
+                        "back": card["back"],
+                        "user_answer": ua,
+                        "correct": correct,
+                    })
+                    ss[key + "test_results"] = results
+                    ss[key + "test_pos"] = pos + 1
+                    st.experimental_rerun()
+
+    # =======================================================
+    # DECK AT A GLANCE (FULL WIDTH)
+    # =======================================================
+    st.markdown("---")
+    st.subheader("Deck at a glance")
+
+    df_rows = []
+    for i, c in enumerate(cards, start=1):
+        df_rows.append({
+            "#": i,
+            "Front": c.get("front", ""),
+            "Back": c.get("back", ""),
+            "Score": c.get("score", 0),
+            "Reviews": c.get("reviews", 0),
+        })
+
+    st.dataframe(pd.DataFrame(df_rows), height=500, use_container_width=True)
+
+
+
+
+###############################################################
+# QUIZ TAB
+###############################################################
+
+def quiz_tab(username: str):
+    st.header("Quiz")
+    ensure_default_decks(username)
+
+    user_dir = get_user_dir(username)
+    quiz_dir = user_dir / "quizzes"
+    quiz_dir.mkdir(exist_ok=True)
+
+    decks = list_user_decks(username)
+    if not decks:
+        st.info("No decks.")
+        return
+
+    selected = st.multiselect("Use decks", sorted(decks.keys()))
+    if not selected:
+        return
+
+    num_q = st.slider("Questions", 3, 20, 6)
+
+    if st.button("Generate quiz"):
+        pool = []
+        for name in selected:
+            pool.extend(load_deck(decks[name])["cards"])
+
+        questions = []
+        for _ in range(num_q):
+            c = random.choice(pool)
+            qtype = random.choice(["mc", "fill"])
+            if qtype == "mc":
+                others = random.sample(pool, min(3, len(pool) - 1))
+                opts = [c["back"]] + [x["back"] for x in others]
+                random.shuffle(opts)
+                questions.append(
+                    {"type": "mc", "prompt": c["front"], "options": opts, "answer": c["back"]}
+                )
+            else:
+                questions.append(
+                    {"type": "fill", "prompt": c["front"], "answer": c["back"]}
+                )
+
+        qid = datetime.utcnow().strftime("quiz_%Y%m%d_%H%M%S")
+        quiz = {"id": qid, "questions": questions}
+        (quiz_dir / f"{qid}.json").write_text(json.dumps(quiz, indent=2))
+
+        st.session_state["quiz"] = quiz
+        st.session_state["quiz_idx"] = 0
+        st.session_state["quiz_answers"] = {}
+        st.success("Quiz created!")
+
+    if "quiz" not in st.session_state:
+        return
+
+    quiz = st.session_state["quiz"]
+    qs = quiz["questions"]
+    idx = st.session_state["quiz_idx"]
+
+    if idx >= len(qs):
+        correct = sum(1 for v in st.session_state["quiz_answers"].values() if v["correct"])
+        st.success(f"Score: {correct}/{len(qs)}")
+        if st.button("New quiz"):
+            del st.session_state["quiz"]
+            del st.session_state["quiz_idx"]
+            del st.session_state["quiz_answers"]
+        return
+
+    q = qs[idx]
+    st.subheader(f"Question {idx+1}/{len(qs)}")
+    st.markdown(f"**{q['prompt']}**")
+
+    if q["type"] == "mc":
+        choice = st.radio("Choose:", q["options"], key=f"mc_{idx}")
+        if st.button("Submit", key=f"sub_{idx}"):
+            st.session_state["quiz_answers"][idx] = {
+                "given": choice,
+                "correct": choice == q["answer"],
+            }
+            st.session_state["quiz_idx"] += 1
+            st.experimental_rerun()
+    else:
+        ans = st.text_input("Your answer", key=f"fill_{idx}")
+        if st.button("Submit", key=f"sub_{idx}"):
+            st.session_state["quiz_answers"][idx] = {
+                "given": ans,
+                "correct": ans.strip().lower() == q["answer"].lower(),
+            }
+            st.session_state["quiz_idx"] += 1
+            st.experimental_rerun()
+
+
+###############################################################
+# MAIN
+###############################################################
+
+def main():
+    # ---------- AUTH ----------
+    if "user" not in st.session_state:
+        login_view()
+        return
+
+    username = st.session_state["user"]
+    st.sidebar.write(f"Logged in as **{username}**")
+
+    if st.sidebar.button("Log out"):
+        st.session_state.clear()
+        st.experimental_rerun()
+
+    # ---------- LOAD MODELS + PREFS ----------
+    preload_models()
+    sidebar_settings(username)
+    ensure_default_decks(username)
+
+    # ---------- TAB PERSISTENCE ----------
+    if "active_tab" not in st.session_state:
+        st.session_state["active_tab"] = 0
+
+    tab_labels = ["Dashboard", "Conversation", "OCR", "Flashcards", "Quiz", "Settings"]
+    tabs = st.tabs(tab_labels)
+
+    tab_dash, tab_conv, tab_ocr, tab_flash, tab_quiz, tab_settings = tabs
+
+    # restore active tab (required so Streamlit shows correct tab on rerun)
+    _ = tabs[st.session_state["active_tab"]]
+
+    with tab_dash:
+        st.session_state["active_tab"] = 0
+        dashboard_tab(username)
+
+    with tab_conv:
+        st.session_state["active_tab"] = 1
+        conversation_tab(username)
+
+    with tab_ocr:
+        st.session_state["active_tab"] = 2
+        ocr_tab(username)
+
+    with tab_flash:
+        st.session_state["active_tab"] = 3
+        flashcards_tab(username)
+
+    with tab_quiz:
+        st.session_state["active_tab"] = 4
+        quiz_tab(username)
+
+    with tab_settings:
+        st.session_state["active_tab"] = 5
+        settings_tab(username)
+
+
+
+if __name__ == "__main__":
+    main()
+
+

src/app/ocr_tools.py

@@ -0,0 +1,64 @@
+
+# src/app/ocr_tools.py
+
+import io
+from typing import Any, Dict, List, Optional
+
+from PIL import Image
+import pytesseract
+from deep_translator import GoogleTranslator
+
+
+def _simple_ocr(image_bytes: bytes) -> str:
+    """
+    Fallback OCR using pytesseract.
+    """
+    img = Image.open(io.BytesIO(image_bytes)).convert("RGB")
+    text = pytesseract.image_to_string(img)
+    return text.strip()
+
+
+def ocr_and_translate_batch(
+    images: List[bytes],
+    target_lang: str = "en",
+    prefer_ocr_local: bool = True,
+) -> List[Dict]:
+    """
+    Runs OCR on a batch of images. For now, we always use the
+    simple pytesseract-based OCR, but the 'prefer_ocr_local'
+    flag is kept for compatibility with previous versions that
+    used a local PaddleOCR pipeline.
+
+    Returns: list of dicts with keys:
+      - "text": original OCR text
+      - "translation": translation into target_lang
+      - "target_lang": target_lang
+    """
+    translator = GoogleTranslator(source="auto", target=target_lang)
+
+    results: List[Dict] = []
+    for img_bytes in images:
+        text = _simple_ocr(img_bytes)
+        if text:
+            try:
+                translated = translator.translate(text)
+            except Exception:
+                translated = ""
+
+            results.append(
+                {
+                    "text": text,
+                    "translation": translated,
+                    "target_lang": target_lang,
+                }
+            )
+        else:
+            results.append(
+                {
+                    "text": "",
+                    "translation": "",
+                    "target_lang": target_lang,
+                }
+            )
+    return results
+

src/app/quiz_tools.py

@@ -0,0 +1,59 @@
+
+# src/app/quiz_tools.py
+
+# Placeholder restored because modifications moved to main_app.
+# This keeps the file present so import does not fail.
+
+import json
+import random
+from datetime import datetime
+
+def create_semantic_quiz_for_user(username: str, topic: str, num_questions: int = 5):
+    reading_passages = [
+        f"{topic.capitalize()} is important in daily life. Many people enjoy talking about it.",
+        f"Here is a short story based on the topic '{topic}'.",
+        f"In this short description, you will learn more about {topic}.",
+    ]
+
+    questions = []
+    for i in range(num_questions):
+        passage = random.choice(reading_passages)
+        q_type = random.choice(["translate_phrase", "summarize", "interpret"])
+
+        if q_type == "translate_phrase":
+            questions.append({
+                "type": "semantic_translate_phrase",
+                "prompt": f"Translate:
+
+'{passage}'",
+                "answer": "(model evaluated)",
+                "explanation": f"Checks ability to translate topic '{topic}'."
+            })
+        elif q_type == "summarize":
+            questions.append({
+                "type": "semantic_summarize",
+                "prompt": f"Summarize:
+
+{passage}",
+                "answer": "(model evaluated)",
+                "explanation": f"Checks comprehension of topic '{topic}'."
+            })
+        elif q_type == "interpret":
+            questions.append({
+                "type": "semantic_interpret",
+                "prompt": f"Interpret meaning:
+
+{passage}",
+                "answer": "(model evaluated)",
+                "explanation": f"Checks conceptual understanding of '{topic}'."
+            })
+
+    ts = datetime.utcnow().strftime("%Y-%m-%dT%H-%M-%SZ")
+    quiz_id = f"semantic_quiz_{ts}"
+
+    return {
+        "id": quiz_id,
+        "created_at": ts,
+        "topic": topic,
+        "questions": questions,
+    }

src/app/viewers.py

@@ -0,0 +1,272 @@
+
+# src/app/viewers.py
+
+import json
+from pathlib import Path
+from typing import Dict, List
+
+from app.config import get_user_dir
+from app.flashcards_tools import load_deck
+
+
+def _build_flipbook_html(deck_name: str, cards: List[Dict]) -> str:
+    """
+    Builds a simple HTML+JS flip-style viewer for a deck of cards.
+    Front = card['front'], Back = card['back'].
+    """
+    js_cards = json.dumps(
+        [
+            {"front": c.get("front", ""), "back": c.get("back", "")}
+            for c in cards
+        ],
+        ensure_ascii=False,
+    )
+
+    html = f"""<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8" />
+<title>Flashcards — {deck_name}</title>
+<style>
+body {{
+    background: #111;
+    color: #eee;
+    font-family: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+    padding: 1.5rem;
+}}
+
+.wrapper {{
+    max-width: 700px;
+    margin: 0 auto;
+}}
+
+h1 {{
+    text-align: center;
+    margin-bottom: 1rem;
+}}
+
+.card-container {{
+    perspective: 1000px;
+    margin-bottom: 1rem;
+}}
+
+.card {{
+    position: relative;
+    width: 100%;
+    height: 250px;
+    border-radius: 16px;
+    background: #222;
+    box-shadow: 0 8px 15px rgba(0,0,0,0.4);
+    transition: transform 0.6s;
+    transform-style: preserve-3d;
+    cursor: pointer;
+}}
+
+.card.flipped {{
+    transform: rotateY(180deg);
+}}
+
+.card-face {{
+    position: absolute;
+    inset: 0;
+    border-radius: 16px;
+    backface-visibility: hidden;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    padding: 1rem;
+}}
+
+.card-face.front {{
+    background: #333;
+}}
+
+.card-face.back {{
+    background: #1a73e8;
+    transform: rotateY(180deg);
+}}
+
+.card-text {{
+    font-size: 2.2rem;
+    text-align: center;
+    word-wrap: break-word;
+}}
+
+.controls {{
+    display: flex;
+    justify-content: center;
+    gap: 0.75rem;
+    margin-bottom: 0.5rem;
+}}
+
+button {{
+    background: #333;
+    color: #eee;
+    border-radius: 999px;
+    border: none;
+    padding: 0.5rem 1rem;
+    font-size: 0.95rem;
+    cursor: pointer;
+    transition: background 0.2s ease, transform 0.1s ease;
+}}
+
+button:hover {{
+    background: #444;
+    transform: translateY(-1px);
+}}
+
+.meta {{
+    text-align: center;
+    margin-top: 0.25rem;
+    font-size: 0.9rem;
+    color: #ccc;
+}}
+
+.badge {{
+    display: inline-block;
+    padding: 0.1rem 0.75rem;
+    border-radius: 999px;
+    font-size: 0.8rem;
+    background: #555;
+    margin-left: 0.5rem;
+}}
+</style>
+</head>
+<body>
+<div class="wrapper">
+  <h1>{deck_name}</h1>
+  <div class="card-container">
+    <div class="card" id="card">
+      <div class="card-face front">
+        <div class="card-text" id="cardFront"></div>
+      </div>
+      <div class="card-face back">
+        <div class="card-text" id="cardBack"></div>
+      </div>
+    </div>
+  </div>
+
+  <div class="controls">
+    <button id="prevBtn">⏮ Prev</button>
+    <button id="flipBtn">🔁 Flip</button>
+    <button id="nextBtn">Next ⏭</button>
+    <button id="shuffleBtn">🔀 Shuffle</button>
+  </div>
+
+  <div class="meta">
+    <span id="cardIndex">Card 0 / 0</span>
+    <span class="badge" id="sideLabel">Front</span>
+  </div>
+</div>
+
+<script>
+const cards = {js_cards};
+let currentIndex = 0;
+let isFlipped = false;
+
+const cardEl = document.getElementById('card');
+const frontEl = document.getElementById('cardFront');
+const backEl = document.getElementById('cardBack');
+const indexEl = document.getElementById('cardIndex');
+const sideLabelEl = document.getElementById('sideLabel');
+
+function renderCard() {{
+    if (!cards.length) {{
+        frontEl.textContent = "(No cards)";
+        backEl.textContent = "";
+        indexEl.textContent = "Card 0 / 0";
+        sideLabelEl.textContent = "Front";
+        cardEl.classList.remove('flipped');
+        return;
+    }}
+
+    const card = cards[currentIndex];
+    frontEl.textContent = card.front || "";
+    backEl.textContent = card.back || "";
+
+    indexEl.textContent = "Card " + (currentIndex + 1) + " / " + cards.length;
+    sideLabelEl.textContent = isFlipped ? "Back" : "Front";
+}}
+
+function flipCard() {{
+    if (!cards.length) return;
+    isFlipped = !isFlipped;
+    if (isFlipped) {{
+        cardEl.classList.add('flipped');
+    }} else {{
+        cardEl.classList.remove('flipped');
+    }}
+    sideLabelEl.textContent = isFlipped ? "Back" : "Front";
+}}
+
+function nextCard() {{
+    if (!cards.length) return;
+    currentIndex = (currentIndex + 1) % cards.length;
+    isFlipped = false;
+    cardEl.classList.remove('flipped');
+    renderCard();
+}}
+
+function prevCard() {{
+    if (!cards.length) return;
+    currentIndex = (currentIndex - 1 + cards.length) % cards.length;
+    isFlipped = false;
+    cardEl.classList.remove('flipped');
+    renderCard();
+}}
+
+function shuffleCards() {{
+    for (let i = cards.length - 1; i > 0; i--) {{
+        const j = Math.floor(Math.random() * (i + 1));
+        [cards[i], cards[j]] = [cards[j], cards[i]];
+    }}
+    currentIndex = 0;
+    isFlipped = false;
+    cardEl.classList.remove('flipped');
+    renderCard();
+}}
+
+cardEl.addEventListener('click', flipCard);
+document.getElementById('flipBtn').addEventListener('click', flipCard);
+document.getElementById('nextBtn').addEventListener('click', nextCard);
+document.getElementById('prevBtn').addEventListener('click', prevCard);
+document.getElementById('shuffleBtn').addEventListener('click', shuffleCards);
+
+document.addEventListener('keydown', (e) => {{
+    if (!cards.length) return;
+    if (e.code === "ArrowRight") nextCard();
+    else if (e.code === "ArrowLeft") prevCard();
+    else if (e.code === "Space") {{
+        e.preventDefault();
+        flipCard();
+    }}
+}});
+
+renderCard();
+</script>
+</body>
+</html>
+"""
+    return html
+
+
+def generate_flashcard_viewer_for_user(username: str, deck_path: Path) -> Path:
+    """
+    Generates an HTML flipbook viewer for the given deck in the user's
+    /viewers directory, and returns the path to the HTML file.
+    """
+    deck = load_deck(deck_path)
+    deck_name = deck.get("name", deck_path.stem)
+    cards = deck.get("cards", [])
+
+    html_str = _build_flipbook_html(deck_name, cards)
+
+    user_dir = get_user_dir(username)
+    viewer_dir = user_dir / "viewers"
+    viewer_dir.mkdir(parents=True, exist_ok=True)
+
+    safe_name = deck_path.stem
+    out_path = viewer_dir / f"{safe_name}_viewer.html"
+    out_path.write_text(html_str, encoding="utf-8")
+    return out_path
+

src/generate_flashcard_viewer.py

@@ -0,0 +1,32 @@
+
+# src/generate_flashcard_viewer.py
+
+"""
+Utility script to generate a standalone HTML viewer for a given
+user's flashcard deck. Typically, the Streamlit app calls
+app.viewers.generate_flashcard_viewer_for_user directly.
+"""
+
+import argparse
+from pathlib import Path
+
+from app.viewers import generate_flashcard_viewer_for_user
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--user", required=True, help="Username")
+    parser.add_argument("--deck", required=True, help="Path to deck JSON")
+    args = parser.parse_args()
+
+    deck_path = Path(args.deck)
+    if not deck_path.exists():
+        raise FileNotFoundError(deck_path)
+
+    out_path = generate_flashcard_viewer_for_user(args.user, deck_path)
+    print(f"Viewer written to: {out_path}")
+
+
+if __name__ == "__main__":
+    main()
+

src/generate_quiz.py

@@ -0,0 +1,2 @@
+
+print("Deprecated — use quiz inside Streamlit UI")

src/generate_quiz_viewer.py

@@ -0,0 +1,2 @@
+
+print("Viewer now handled by app.viewers")