deploy: sync backend (real general answers, casual short-circuit, classifier, chat resilience)

backend/Dockerfile

@@ -5,7 +5,8 @@ ENV PYTHONDONTWRITEBYTECODE=1 \
     UPLOAD_DIR=/app/uploads \
     TTS_OUTPUT_DIR=/app/generated/audio \
     GENERATED_VIDEO_JOBS_DIR=/app/generated-video-jobs \
-    GENERATED_VIDEO_OUTPUT_DIR=/app/generated-videos
+    GENERATED_VIDEO_OUTPUT_DIR=/app/generated-videos \
+    LEARN_LESSON_CACHE_DIR=/app/generated/learn-anything
 
 WORKDIR /app
 

backend/app/main.py

@@ -1,5 +1,6 @@
 from collections.abc import AsyncIterator
 from contextlib import asynccontextmanager
+from pathlib import Path
 
 import logging
 import time
@@ -778,3 +779,14 @@ app.mount(
     StaticFiles(directory=settings.resolved_generated_video_output_dir, check_dir=False),
     name="generated-videos",
 )
+# Learn Anything lesson cache (manifests + per-beat audio). Must live under a
+# writable path on Hugging Face (/app/generated/...), not monorepo public/.
+_learn_lesson_static = (
+    Path(__file__).resolve().parents[1] / "generated" / "learn-anything"
+)
+_learn_lesson_static.mkdir(parents=True, exist_ok=True)
+app.mount(
+    "/generated/learn-anything",
+    StaticFiles(directory=_learn_lesson_static, check_dir=False),
+    name="generated-learn-lessons",
+)

backend/app/routes/learning_engine.py

@@ -196,3 +196,20 @@ def generate_learn_lesson(
         )
     except LessonBuildError as exc:
         raise HTTPException(status_code=status.HTTP_502_BAD_GATEWAY, detail=str(exc)) from exc
+    except Exception as exc:
+        # Surface a clear student-safe message instead of the global 500
+        # "internal error" envelope (common when cache paths fail on HF).
+        import logging
+
+        logging.getLogger(__name__).exception(
+            "Unhandled learn-lesson failure for topic=%s lesson=%s",
+            payload.topic,
+            payload.lesson_title,
+        )
+        raise HTTPException(
+            status_code=status.HTTP_502_BAD_GATEWAY,
+            detail=(
+                f"Could not prepare this class ({type(exc).__name__}). "
+                "Your plan is still saved — retry in a moment."
+            ),
+        ) from exc

backend/app/services/learn_lesson_builder.py

@@ -32,12 +32,15 @@ from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any
 
-from app.core.config import PROJECT_ROOT, get_settings
+from app.core.config import BACKEND_DIR, PROJECT_ROOT, get_settings
 
 logger = logging.getLogger(__name__)
 
-# Served to the browser under /generated/learn-anything/<hash>/...
-PUBLIC_ROOT = PROJECT_ROOT / "public" / "generated" / "learn-anything"
+# Writable cache for lesson manifests + audio. On Hugging Face Docker the
+# backend tree is /app, so PROJECT_ROOT/public is outside the container and
+# not writable (PermissionError → opaque 500). Cache under BACKEND_DIR.
+# Tests may monkeypatch this path.
+PUBLIC_ROOT = BACKEND_DIR / "generated" / "learn-anything"
 
 GROQ_URL = "https://api.groq.com/openai/v1/chat/completions"
 # llama-4-scout was retired from Groq; 3.3-70b is the strongest current chat model.
@@ -757,6 +760,28 @@ def _lesson_lock_for(key: str) -> threading.Lock:
         return lock
 
 
+def ensure_public_root() -> Path:
+    """Ensure the lesson cache directory exists and is writable."""
+    env = _env("LEARN_LESSON_CACHE_DIR")
+    root = Path(env) if env else PUBLIC_ROOT
+    try:
+        root.mkdir(parents=True, exist_ok=True)
+        probe = root / ".write_probe"
+        probe.write_text("ok", encoding="utf-8")
+        probe.unlink(missing_ok=True)
+        return root
+    except OSError:
+        fallback = Path(os.getenv("TMPDIR") or os.getenv("TEMP") or "/tmp") / "docdoe-learn-lessons"
+        try:
+            fallback.mkdir(parents=True, exist_ok=True)
+            logger.warning("Lesson cache fell back to %s", fallback)
+            return fallback
+        except OSError as exc:
+            raise LessonBuildError(
+                f"Lesson cache directory is not writable ({root}): {exc}"
+            ) from exc
+
+
 def build_lesson(
     *,
     topic: str,
@@ -783,7 +808,8 @@ def build_lesson(
         else (_env("DOCDOE_TTS_MODEL") or "aura-luna-en")
     )
     key = lesson_hash(topic, lesson_title, level, medium, voice)
-    out_dir = PUBLIC_ROOT / key
+    cache_root = ensure_public_root()
+    out_dir = cache_root / key
     manifest_path = out_dir / "lesson.json"
 
     if manifest_path.exists() and not force:
@@ -806,7 +832,12 @@ def build_lesson(
                 context=context,
             )
         )
-        out_dir.mkdir(parents=True, exist_ok=True)
+        try:
+            out_dir.mkdir(parents=True, exist_ok=True)
+        except OSError as exc:
+            raise LessonBuildError(
+                f"Could not create lesson cache folder ({out_dir}): {exc}"
+            ) from exc
         delivery_mode = "reading" if mock_mode else "audio"
         delivery_notice = (
             "Local preview: this complete starter class is available in reading mode; no generated voice is being presented as real audio."