elkay: api.py, chatbot

utils/api.py

@@ -1,29 +1,22 @@
-"""
-Frontend HTTP client for the FinBack backend (running on HF Spaces).
-- Uses a single requests.Session with retries
-- Exposes small helpers for tutor chat, retrieval, auth, classes, lessons, quizzes, games
-- Assumes the environment var BACKEND_URL is set in the Frontend Space
-"""
-from __future__ import annotations
-import os
-import logging
-from typing import Any, Dict, List, Optional
-import requests
+import os, json, requests, logging
 from urllib3.util.retry import Retry
 from requests.adapters import HTTPAdapter
 
-# ----------------------------------------------------------------------------
-# Config & session
-# ----------------------------------------------------------------------------
+# ---- Setup ----
 BACKEND = (os.getenv("BACKEND_URL") or "").strip().rstrip("/")
 if not BACKEND:
     raise RuntimeError("BACKEND_URL is not set in Space secrets.")
 
+BACKEND_URL = os.getenv("BACKEND_URL")
+
 TOKEN = (os.getenv("BACKEND_TOKEN") or os.getenv("HF_TOKEN") or "").strip()
+
+# Increased timeout for potential late-night latency
 DEFAULT_TIMEOUT = int(os.getenv("BACKEND_TIMEOUT", "60"))
 
 _session = requests.Session()
-_retry = Retry(
+
+retry = Retry(
     total=3,
     connect=3,
     read=3,
@@ -31,8 +24,9 @@ _retry = Retry(
     status_forcelist=(429, 500, 502, 503, 504),
     allowed_methods=frozenset(["GET", "POST", "PUT", "PATCH", "DELETE"]),
 )
-_session.mount("https://", HTTPAdapter(max_retries=_retry))
-_session.mount("http://", HTTPAdapter(max_retries=_retry))
+_session.mount("https://", HTTPAdapter(max_retries=retry))
+_session.mount("http://", HTTPAdapter(max_retries=retry))
+
 _session.headers.update({
     "Accept": "application/json, */*;q=0.1",
     "User-Agent": "FinEdu-Frontend/1.0 (+spaces)",
@@ -40,302 +34,524 @@ _session.headers.update({
 if TOKEN:
     _session.headers["Authorization"] = f"Bearer {TOKEN}"
 
+# Setup logging for debugging
+logging.basicConfig(level=logging.DEBUG)
 logger = logging.getLogger(__name__)
-logging.basicConfig(level=logging.INFO)
-
-# ----------------------------------------------------------------------------
-# Low-level HTTP helpers
-# ----------------------------------------------------------------------------
-
-def _json_or_raise(resp: requests.Response) -> Dict[str, Any] | List[Any]:
-    """Return JSON or raise a readable error."""
-    try:
-        resp.raise_for_status()
-    except requests.HTTPError as e:
-        body = (getattr(resp, "text", "") or "")[:500]
-        status = getattr(resp, "status_code", "?")
-        if status in (401, 403):
-            raise RuntimeError(
-                f"Auth rejected [{status}]. Check BACKEND_TOKEN/HF_TOKEN and backend privacy settings. Body: {body}"
-            ) from e
-        raise RuntimeError(f"HTTP {status}: {body}") from e
 
+def _json_or_raise(resp: requests.Response):
     ctype = resp.headers.get("content-type", "")
     if "application/json" in ctype:
         return resp.json()
-    # best-effort
     try:
         return resp.json()
     except Exception:
         snippet = (resp.text or "")[:300]
-        raise RuntimeError(f"Expected JSON but got {ctype or 'unknown'}: {snippet}")
+        raise RuntimeError(f"Expected JSON but got {ctype or 'unknown'}:\n{snippet}")
 
-def _req(method: str, path: str, **kw) -> requests.Response:
+def _req(method: str, path: str, **kw):
     if not path.startswith("/"):
         path = "/" + path
     url = f"{BACKEND}{path}"
     kw.setdefault("timeout", DEFAULT_TIMEOUT)
-    return _session.request(method, url, **kw)
-
-# ----------------------------------------------------------------------------
-# Health
-# ----------------------------------------------------------------------------
-
-def health() -> Dict[str, Any]:
-    return _json_or_raise(_req("GET", "/health"))  # should return local_model, embedding_model
+    try:
+        r = _session.request(method, url, **kw)
+        r.raise_for_status()
+    except requests.HTTPError as e:
+        body = ""
+        try:
+            body = r.text[:500]
+        except Exception:
+            pass
+        status = getattr(r, "status_code", "?")
+        if status in (401, 403):
+            raise RuntimeError(
+                f"{method} {path} failed [{status}] – auth rejected. "
+                f"Check BACKEND_TOKEN/HF_TOKEN permissions and that the backend Space is private/readable."
+            ) from e
+        raise RuntimeError(f"{method} {path} failed [{status}]: {body}") from e
+    except requests.RequestException as e:
+        raise RuntimeError(f"{method} {path} failed: {e.__class__.__name__}: {e}") from e
+    return r
 
-# ----------------------------------------------------------------------------
-# RAG + Chat
-# ----------------------------------------------------------------------------
+# ---- Health ----
+def health():
+    try:
+        return _json_or_raise(_req("GET", "/health"))
+    except Exception:
+        try:
+            _req("GET", "/")
+            return {"ok": True}
+        except Exception:
+            return {"ok": False}
+        
+# --- Optional API prefix (e.g., "/api" or "/v1")
+API_PREFIX_ENV = (os.getenv("BACKEND_API_PREFIX") or "").strip().rstrip("/")
+
+def _prefixes():
+    if API_PREFIX_ENV:
+        return ["/" + API_PREFIX_ENV.strip("/"), ""]
+    return [""]
+
+def _try_candidates(method: str, candidates: list[tuple[str, dict]]):
+    tried = []
+    for pref in _prefixes():
+        for path, kw in candidates:
+            url = f"{BACKEND}{pref}{path}"
+            tried.append(f"{method} {url}")
+            try:
+                r = _session.request(method, url, timeout=DEFAULT_TIMEOUT, **kw)
+            except requests.RequestException as e:
+                continue
+            if r.status_code in (401, 403):
+                snippet = (r.text or "")[:200]
+                raise RuntimeError(f"{method} {path} auth failed [{r.status_code}]: {snippet}")
+            if 200 <= r.status_code < 300:
+                return _json_or_raise(r)
+    raise RuntimeError("No matching endpoint for this operation. Tried:\n- " + "\n- ".join(tried))
+
+
+
+
+class _BackendError(Exception):
+    pass
+
+def _get(url, params=None, timeout=30):
+    if not BACKEND_URL:
+        raise _BackendError("BACKEND_URL is not set")
+    r = requests.get(f"{BACKEND_URL}{url}", params=params or {}, timeout=timeout)
+    r.raise_for_status()
+    return r.json()
+
+def _post(url, json=None, timeout=60):
+    if not BACKEND_URL:
+        raise _BackendError("BACKEND_URL is not set")
+    r = requests.post(f"{BACKEND_URL}{url}", json=json or {}, timeout=timeout)
+    r.raise_for_status()
+    return r.json()
 
 def retrieve(query: str, lesson_id: int, level_slug: str = "beginner", k: int = 5) -> str:
-    data = _json_or_raise(_req(
-        "GET", "/retrieve",
-        params={"query": query, "lesson_id": lesson_id, "level_slug": level_slug, "k": k},
-    ))
-    return str(data.get("context", ""))
+    try:
+        data = _get("/retrieve", params={"query": query, "lesson_id": lesson_id, "level_slug": level_slug, "k": k})
+        return data.get("context", "")
+    except Exception as e:
+        return f"(retrieval failed: {e})"
 
-def chat_ai(query: str, lesson_id: int, level_slug: str, history: Optional[List[Dict[str, str]]] = None) -> str:
+def chat_ai(query: str, lesson_id: int, level_slug: str, history=None) -> str:
     payload = {
         "query": query,
-        "lesson_id": int(lesson_id) if lesson_id is not None else 0,
+        "lesson_id": lesson_id,
         "level_slug": level_slug or "beginner",
-        "history": history or [],
+        "history": history or []
     }
-    data = _json_or_raise(_req("POST", "/chat", json=payload, timeout=90))
-    return str(data.get("answer", ""))
+    try:
+        data = _post("/chat", json=payload, timeout=90)
+        return data.get("answer", "")
+    except Exception as e:
+        return f"(chat failed: {e})"
+    
+
+
+# -- Helpers for student_db.py
+def user_stats(student_id: int):
+    return _req("GET", f"/students/{student_id}/stats").json()
+def list_assignments_for_student(student_id: int):
+    return _req("GET", f"/students/{student_id}/assignments").json()
+def student_quiz_average(student_id: int):
+    d = _req("GET", f"/students/{student_id}/quiz_avg").json()
+    if isinstance(d, dict):
+        for k in ("avg", "average", "score_pct", "score", "value"):
+            if k in d:
+                v = d[k]
+                break
+        else:
+            v = next((vv for vv in d.values() if isinstance(vv, (int, float, str))), 0)
+    else:
+        v = d
+    try:
+        return int(round(float(str(v).strip().rstrip("%"))))
+    except Exception:
+        return 0
+def recent_lessons_for_student(student_id: int, limit: int = 5):
+    return _req("GET", f"/students/{student_id}/recent", params={"limit": limit}).json()
+
+# -- Teacher endpoints (backend Space)
+def create_class(teacher_id: int, name: str):
+    return _try_candidates("POST", [
+        (f"/teachers/{teacher_id}/classes", {"json": {"name": name}}),
+        ("/classes", {"json": {"teacher_id": teacher_id, "name": name}}),
+    ])
+
+def teacher_tiles(teacher_id: int):
+    return _json_or_raise(_req("GET", f"/teachers/{teacher_id}/tiles"))
+
+def list_classes_by_teacher(teacher_id: int):
+    return _try_candidates("GET", [
+        (f"/teachers/{teacher_id}/classes", {}),
+    ])
+
+def class_student_metrics(class_id: int):
+    return _try_candidates("GET", [
+        (f"/classes/{class_id}/students/metrics", {}),
+        (f"/classes/{class_id}/student_metrics", {}),
+        (f"/classes/{class_id}/students", {}),
+    ])
+
+def class_weekly_activity(class_id: int):
+    return _try_candidates("GET", [
+        (f"/classes/{class_id}/activity/weekly", {}),
+        (f"/classes/{class_id}/weekly_activity", {}),
+    ])
+
+def class_progress_overview(class_id: int):
+    return _try_candidates("GET", [
+        (f"/classes/{class_id}/progress", {}),
+        (f"/classes/{class_id}/progress_overview", {}),
+    ])
+
+def class_recent_activity(class_id: int, limit=6, days=30):
+    return _try_candidates("GET", [
+        (f"/classes/{class_id}/activity/recent", {"params": {"limit": limit, "days": days}}),
+        (f"/classes/{class_id}/recent_activity", {"params": {"limit": limit, "days": days}}),
+    ])
+
+def list_students_in_class(class_id: int):
+    return _json_or_raise(_req("GET", f"/classes/{class_id}/students"))
 
-# ----------------------------------------------------------------------------
-# Auth
-# ----------------------------------------------------------------------------
+def level_from_xp(xp: int):
+    return _json_or_raise(_req("GET", "/levels/from_xp", params={"xp": xp}))["level"]
 
-def login(email: str, password: str) -> Dict[str, Any]:
-    return _json_or_raise(_req("POST", "/auth/login", json={"email": email, "password": password}))
+# -- teacherlink.py helpers
+def join_class_by_code(student_id: int, code: str):
+    d = _json_or_raise(_req("POST", f"/students/{student_id}/classes/join", json={"code": code}))
+    return d.get("class_id", d)
 
-def signup_student(name: str, email: str, password: str, level_label: str, country_label: str) -> Dict[str, Any]:
-    payload = {
-        "name": name, "email": email, "password": password,
-        "level_label": level_label, "country_label": country_label,
-    }
-    return _json_or_raise(_req("POST", "/auth/signup/student", json=payload))
+def list_classes_for_student(student_id: int):
+    return _json_or_raise(_req("GET", f"/students/{student_id}/classes"))
+
+def class_content_counts(class_id: int):
+    return _try_candidates("GET", [
+        (f"/classes/{class_id}/content_counts", {}),
+        (f"/classes/{class_id}/counts", {}),
+    ])
 
-def signup_teacher(title: str, name: str, email: str, password: str) -> Dict[str, Any]:
-    payload = {"title": title, "name": name, "email": email, "password": password}
-    return _json_or_raise(_req("POST", "/auth/signup/teacher", json=payload))
+def student_class_progress(student_id: int, class_id: int):
+    return _json_or_raise(_req("GET", f"/classes/{class_id}/students/{student_id}/progress"))
 
-# ----------------------------------------------------------------------------
-# Classes
-# ----------------------------------------------------------------------------
+def leave_class(student_id: int, class_id: int):
+    _json_or_raise(_req("POST", f"/classes/{class_id}/leave", json={"student_id": student_id}))
+    return True
 
-def create_class(teacher_id: int, name: str) -> Dict[str, Any]:
-    return _json_or_raise(_req("POST", f"/teachers/{teacher_id}/classes", json={"name": name}))
+def student_assignments_for_class(student_id: int, class_id: int):
+    return _json_or_raise(_req("GET", f"/classes/{class_id}/students/{student_id}/assignments"))
 
-def list_classes_by_teacher(teacher_id: int) -> List[Dict[str, Any]]:
-    return _json_or_raise(_req("GET", f"/teachers/{teacher_id}/classes"))
+# ---------- TEACHERS / CLASSES / CONTENT (BACKEND ROUTES THAT EXIST) ----------
+def create_class(teacher_id: int, name: str):
+    return _try_candidates("POST", [
+        (f"/teachers/{teacher_id}/classes", {"json": {"name": name}}),
+        ("/classes", {"json": {"teacher_id": teacher_id, "name": name}}),
+    ])
 
-def list_students_in_class(class_id: int) -> List[Dict[str, Any]]:
+def list_classes_by_teacher(teacher_id: int):
+    return _try_candidates("GET", [
+        (f"/teachers/{teacher_id}/classes", {}),
+    ])
+
+def list_students_in_class(class_id: int):
     return _json_or_raise(_req("GET", f"/classes/{class_id}/students"))
 
-def class_content_counts(class_id: int) -> Dict[str, Any]:
-    return _json_or_raise(_req("GET", f"/classes/{class_id}/content_counts"))
+def class_content_counts(class_id: int):
+    return _try_candidates("GET", [
+        (f"/classes/{class_id}/content_counts", {}),
+        (f"/classes/{class_id}/counts", {}),
+    ])
 
-def list_class_assignments(class_id: int) -> List[Dict[str, Any]]:
+def list_class_assignments(class_id: int):
     return _json_or_raise(_req("GET", f"/classes/{class_id}/assignments"))
 
-def class_analytics(class_id: int) -> Dict[str, Any]:
+def class_analytics(class_id: int):
     return _json_or_raise(_req("GET", f"/classes/{class_id}/analytics"))
 
-def class_student_metrics(class_id: int) -> Dict[str, Any]:
-    return _json_or_raise(_req("GET", f"/classes/{class_id}/students/metrics"))
-
-def student_class_progress(student_id: int, class_id: int) -> Dict[str, Any]:
-    return _json_or_raise(_req("GET", f"/classes/{class_id}/students/{student_id}/progress"))
-
-def student_assignments_for_class(student_id: int, class_id: int) -> List[Dict[str, Any]]:
-    return _json_or_raise(_req("GET", f"/classes/{class_id}/students/{student_id}/assignments"))
-
-def join_class_by_code(student_id: int, code: str) -> Dict[str, Any]:
-    return _json_or_raise(_req("POST", f"/students/{student_id}/classes/join", json={"code": code}))
+def teacher_tiles(teacher_id: int):
+    return _json_or_raise(_req("GET", f"/teachers/{teacher_id}/tiles"))
+
+def class_student_metrics(class_id: int):
+    return _try_candidates("GET", [
+        (f"/classes/{class_id}/students/metrics", {}),
+        (f"/classes/{class_id}/student_metrics", {}),
+        (f"/classes/{class_id}/students", {}),
+    ])
+
+def class_weekly_activity(class_id: int):
+    return _try_candidates("GET", [
+        (f"/classes/{class_id}/activity/weekly", {}),
+        (f"/classes/{class_id}/weekly_activity", {}),
+    ])
+
+def class_progress_overview(class_id: int):
+    return _try_candidates("GET", [
+        (f"/classes/{class_id}/progress", {}),
+        (f"/classes/{class_id}/progress_overview", {}),
+    ])
+
+def class_recent_activity(class_id: int, limit=6, days=30):
+    return _try_candidates("GET", [
+        (f"/classes/{class_id}/activity/recent", {"params": {"limit": limit, "days": days}}),
+        (f"/classes/{class_id}/recent_activity", {"params": {"limit": limit, "days": days}}),
+    ])
 
-def leave_class(student_id: int, class_id: int) -> bool:
-    _json_or_raise(_req("POST", f"/classes/{class_id}/leave", json={"student_id": student_id}))
-    return True
-
-# ----------------------------------------------------------------------------
 # Lessons
-# ----------------------------------------------------------------------------
-
-def list_lessons_by_teacher(teacher_id: int) -> List[Dict[str, Any]]:
+def list_lessons_by_teacher(teacher_id: int):
     return _json_or_raise(_req("GET", f"/teachers/{teacher_id}/lessons"))
 
-def create_lesson(teacher_id: int, title: str, description: str, subject: str, level: str, sections: List[Dict[str, Any]]) -> int:
-    payload = {"title": title, "description": description, "subject": subject, "level": level, "sections": sections}
-    d = _json_or_raise(_req("POST", f"/teachers/{teacher_id}/lessons", json=payload))
-    return int(d.get("lesson_id", d.get("id", 0)))
+def create_lesson(teacher_id: int, title: str, description: str,
+                  subject: str, level: str, sections: list[dict]):
+    payload = {
+        "title": title,
+        "description": description,
+        "subject": subject,
+        "level": level,
+        "sections": sections,
+    }
+    d = _try_candidates("POST", [
+        (f"/teachers/{teacher_id}/lessons", {"json": payload}),
+        ("/lessons", {"json": {"teacher_id": teacher_id, **payload}}),
+    ])
+    return d.get("lesson_id", d.get("id", d))
 
-def get_lesson(lesson_id: int) -> Dict[str, Any]:
+def get_lesson(lesson_id: int):
     return _json_or_raise(_req("GET", f"/lessons/{lesson_id}"))
 
-def update_lesson(lesson_id: int, teacher_id: int, title: str, description: str, subject: str, level: str, sections: List[Dict[str, Any]]) -> bool:
-    d = _json_or_raise(_req("PUT", f"/lessons/{lesson_id}", json={
-        "teacher_id": teacher_id, "title": title, "description": description,
-        "subject": subject, "level": level, "sections": sections,
-    }))
+def update_lesson(lesson_id: int, teacher_id: int, title: str, description: str,
+                  subject: str, level: str, sections: list[dict]):
+    d = _req("PUT", f"/lessons/{lesson_id}", json={
+        "teacher_id": teacher_id,
+        "title": title,
+        "description": description,
+        "subject": subject,
+        "level": level,
+        "sections": sections
+    }).json()
     return bool(d.get("ok", True))
 
-def delete_lesson(lesson_id: int, teacher_id: int) -> tuple[bool, str]:
-    d = _json_or_raise(_req("DELETE", f"/lessons/{lesson_id}", json={"teacher_id": teacher_id}))
-    return bool(d.get("ok", True)), str(d.get("message", ""))
-
-def list_assigned_students_for_lesson(lesson_id: int) -> List[Dict[str, Any]]:
-    return _json_or_raise(_req("GET", f"/lessons/{lesson_id}/assignees"))
+def delete_lesson(lesson_id: int, teacher_id: int):
+    d = _req("DELETE", f"/lessons/{lesson_id}", json={"teacher_id": teacher_id}).json()
+    return bool(d.get("ok", True)), d.get("message", "")
 
-# ----------------------------------------------------------------------------
 # Quizzes
-# ----------------------------------------------------------------------------
-
-def list_quizzes_by_teacher(teacher_id: int) -> List[Dict[str, Any]]:
+def list_quizzes_by_teacher(teacher_id: int):
     return _json_or_raise(_req("GET", f"/teachers/{teacher_id}/quizzes"))
 
-def create_quiz(lesson_id: int, title: str, items: List[Dict[str, Any]], settings: Dict[str, Any]) -> int:
-    d = _json_or_raise(_req("POST", "/quizzes", json={"lesson_id": lesson_id, "title": title, "items": items, "settings": settings}))
-    return int(d.get("quiz_id", d.get("id", 0)))
-
-def get_quiz(quiz_id: int) -> Dict[str, Any]:
-    return _json_or_raise(_req("GET", f"/quizzes/{quiz_id}"))
-
-def update_quiz(quiz_id: int, teacher_id: int, title: str, items: List[Dict[str, Any]], settings: Dict[str, Any]) -> bool:
-    d = _json_or_raise(_req("PUT", f"/quizzes/{quiz_id}", json={
-        "teacher_id": teacher_id, "title": title, "items": items, "settings": settings,
-    }))
-    return bool(d.get("ok", True))
-
-def delete_quiz(quiz_id: int, teacher_id: int) -> tuple[bool, str]:
-    d = _json_or_raise(_req("DELETE", f"/quizzes/{quiz_id}", json={"teacher_id": teacher_id}))
-    return bool(d.get("ok", True)), str(d.get("message", ""))
+def create_quiz(lesson_id: int, title: str, items: list[dict], settings: dict):
+    d = _req("POST", "/quizzes", json={
+        "lesson_id": lesson_id, "title": title, "items": items, "settings": settings
+    }).json()
+    return d.get("quiz_id", d.get("id", d))
 
-def list_assigned_students_for_quiz(quiz_id: int) -> List[Dict[str, Any]]:
-    return _json_or_raise(_req("GET", f"/quizzes/{quiz_id}/assignees"))
+def mark_assignment_started(student_id: int, assignment_id: int):
+    return _req("POST",
+                f"/assignments/{assignment_id}/start",
+                json={"student_id": student_id}).json()
 
-# Backend-side auto quiz generation from lesson chunks
+def set_assignment_progress(student_id: int, assignment_id: int, current_pos: int, progress: float):
+    return _req("PATCH",
+                f"/assignments/{assignment_id}/progress",
+                json={"student_id": student_id, "current_pos": current_pos, "progress": progress}).json()
 
-def generate_quiz(lesson_id: Optional[int], level_slug: Optional[str], lesson_title: Optional[str]) -> List[Dict[str, Any]]:
-    payload = {"lesson_id": lesson_id, "level_slug": level_slug, "lesson_title": lesson_title}
-    d = _json_or_raise(_req("POST", "/quiz/auto", json=payload))
-    return d["items"] if isinstance(d, dict) and "items" in d else (d if isinstance(d, list) else [])
-
-# Submit quiz for grading (backend computes feedback with local model)
+def get_quiz(quiz_id: int):
+    """Fetch a teacher-created quiz (GET /quizzes/{quiz_id}) and return JSON."""
+    return _json_or_raise(_req("GET", f"/quizzes/{quiz_id}"))
 
-def submit_quiz(student_id: int, lesson_id: int, level_slug: str,
-                user_answers: List[Dict[str, Any]], original_quiz: List[Dict[str, Any]],
-                assignment_id: Optional[int] = None) -> Dict[str, Any]:
+def submit_quiz(*, lesson_id: int | None, level_slug: str | None,
+                user_answers: list[dict], original_quiz: list[dict]):
+    """
+    Grade the quiz on the backend. Returns:
+      {"score":{"correct":int,"total":int}, "wrong":[...], "feedback":str}
+    """
     payload = {
-        "student_id": student_id,
-        "lesson_id": lesson_id,
+        "lesson_id": int(lesson_id) if lesson_id is not None else None,
         "level_slug": level_slug,
         "user_answers": user_answers,
         "original_quiz": original_quiz,
-        "assignment_id": assignment_id,
     }
-    return _json_or_raise(_req("POST", "/quiz/grade", json=payload, timeout=90))
-
-# Tutor explanation bullets for wrong answers
-
-def tutor_explain(lesson_id: int, level_slug: str, wrong: List[Dict[str, Any]]) -> Dict[str, Any]:
-    return _json_or_raise(_req("POST", "/tutor/explain", json={
-        "lesson_id": lesson_id, "level_slug": level_slug, "wrong": wrong
-    }))
-
-# ----------------------------------------------------------------------------
-# Assignments & Progress
-# ----------------------------------------------------------------------------
-
-def assign_to_class(class_id: int, teacher_id: int, lesson_id: Optional[int] = None, quiz_id: Optional[int] = None) -> Dict[str, Any]:
-    return _json_or_raise(_req("POST", "/assign", json={
-        "class_id": class_id, "teacher_id": teacher_id, "lesson_id": lesson_id, "quiz_id": quiz_id,
-    }))
+    return _try_candidates("POST", [
+        ("/quiz/submit", {"json": payload}),
+    ])
+
+def update_quiz(quiz_id: int,
+                teacher_id: int, title: str, items: list[dict], settings: dict):
+    d = _req("PUT", f"/quizzes/{quiz_id}", json={
+        "teacher_id": teacher_id, "title": title, "items": items, "settings": settings
+    }).json()
+    return bool(d.get("ok", True))
 
-def mark_assignment_started(student_id: int, assignment_id: int) -> Dict[str, Any]:
-    return _json_or_raise(_req("POST", f"/assignments/{assignment_id}/start", json={"student_id": student_id}))
+def delete_quiz(quiz_id: int, teacher_id: int):
+    d = _req("DELETE", f"/quizzes/{quiz_id}", json={"teacher_id": teacher_id}).json()
+    return bool(d.get("ok", True)), d.get("message", "")
 
-def set_assignment_progress(student_id: int, assignment_id: int, current_pos: int) -> Dict[str, Any]:
-    return _json_or_raise(_req("PATCH", f"/assignments/{assignment_id}/progress", json={
-        "student_id": student_id, "current_pos": current_pos,
-    }))
+def list_assigned_students_for_lesson(lesson_id: int):
+    return _json_or_raise(_req("GET", f"/lessons/{lesson_id}/assignees"))
 
-# ----------------------------------------------------------------------------
-# Student dashboard
-# ----------------------------------------------------------------------------
+def list_assigned_students_for_quiz(quiz_id: int):
+    return _json_or_raise(_req("GET", f"/quizzes/{quiz_id}/assignees"))
 
-def user_stats(student_id: int) -> Dict[str, Any]:
-    return _json_or_raise(_req("GET", f"/students/{student_id}/stats"))
+# Assignments
+def assign_to_class(lesson_id: int | None, quiz_id: int | None, class_id: int, teacher_id: int, due_at: str | None = None):
+    d = _try_candidates("POST", [
+        ("/assign", {"json": {
+            "lesson_id": lesson_id, "quiz_id": quiz_id,
+            "class_id": class_id, "teacher_id": teacher_id, "due_at": due_at
+        }}),
+        ("/assignments", {"json": {
+            "lesson_id": lesson_id, "quiz_id": quiz_id,
+            "class_id": class_id, "teacher_id": teacher_id, "due_at": due_at
+        }}),
+    ])
+    return bool(d.get("ok", True))
 
-def list_assignments_for_student(student_id: int) -> List[Dict[str, Any]]:
-    return _json_or_raise(_req("GET", f"/students/{student_id}/assignments"))
+# ---------- LLM-based quiz generation (backend uses GEN_MODEL) ----------
+def generate_quiz_from_text(content: str, n_questions: int = 5, subject: str = "finance", level: str = "beginner"):
+    return _req("POST", "/quiz/generate", json={
+        "content": content, "n_questions": n_questions, "subject": subject, "level": level
+    }).json()
 
-def student_quiz_average(student_id: int) -> int:
-    d = _json_or_raise(_req("GET", f"/students/{student_id}/quiz_avg"))
-    # Accept various shapes {"avg_pct": int} or similar
-    if isinstance(d, dict):
-        for k in ("avg_pct", "avg", "average", "score_pct", "score", "value"):
-            if k in d:
-                v = d[k]
-                break
-        else:
-            v = next((vv for vv in d.values() if isinstance(vv, (int, float, str))), 0)
-    else:
-        v = d
+def generate_quiz(*, lesson_id: int | None, level_slug: str | None, lesson_title: str | None):
+    payload = {
+        "lesson_id": int(lesson_id) if lesson_id is not None else None,
+        "level_slug": level_slug,
+        "lesson_title": lesson_title,
+    }
+    logger.debug(f"Generating quiz with POST method and payload: {payload}")
     try:
-        return int(round(float(str(v).strip().rstrip("%"))))
-    except Exception:
-        return 0
-
-def recent_lessons_for_student(student_id: int, limit: int = 5) -> List[Dict[str, Any]]:
-    return _json_or_raise(_req("GET", f"/students/{student_id}/recent", params={"limit": int(limit)}))
-
-def list_classes_for_student(student_id: int) -> List[Dict[str, Any]]:
-    return _json_or_raise(_req("GET", f"/students/{student_id}/classes"))
-
-# ----------------------------------------------------------------------------
-# Games
-# ----------------------------------------------------------------------------
-
-def record_money_match_play(user_id: int, target: int, total: int, elapsed_ms: int, matched: bool, gained_xp: Optional[int] = None) -> Dict[str, Any]:
-    payload = {"user_id": user_id, "target": target, "total": total, "elapsed_ms": elapsed_ms, "matched": matched}
-    if gained_xp is not None:
-        payload["gained_xp"] = int(gained_xp)
-    return _json_or_raise(_req("POST", "/games/money_match/record", json=payload))
+        resp = _req("POST", "/quiz/auto", json=payload)
+        logger.debug(f"Raw response from /quiz/auto: {resp.text}")
+        logger.debug(f"Response status code: {resp.status_code}")
+        result = _json_or_raise(resp)
+        # Ensure result is a list of quiz items, handling Qwen's potential JSON structure
+        if isinstance(result, dict) and "items" in result:
+            return result["items"]
+        return result if isinstance(result, list) else []
+    except requests.HTTPError as e:
+        logger.error(f"HTTP Error in quiz generation: {e.response.status_code} - {e.response.text}")
+        return []
+    except RuntimeError as e:
+        logger.error(f"Quiz generation failed: {str(e)}")
+        return []  # Return empty list to prevent app crash
+
+# ---- Legacy agent endpoints (keep) ----
+def start_agent(student_id: int, lesson_id: int, level_slug: str):
+    return _json_or_raise(_req("POST", "/agent/start",
+                               json={"student_id": student_id, "lesson_id": lesson_id, "level_slug": level_slug}))
+
+def get_agent_quiz(student_id: int, lesson_id: int, level_slug: str):
+    d = _json_or_raise(_req("POST", "/agent/quiz",
+                            json={"student_id": student_id, "lesson_id": lesson_id, "level_slug": level_slug}))
+    return d["items"]
+
+def grade_quiz(student_id: int, lesson_id: int, level_slug: str,
+               answers: list[str], assignment_id: int | None = None):
+    d = _json_or_raise(_req("POST", "/agent/grade",
+                            json={"student_id": student_id, "lesson_id": lesson_id, "level_slug": level_slug,
+                                  "answers": answers, "assignment_id": assignment_id}))
+    return d["score"], d["total"]
+
+def next_step(student_id: int, lesson_id: int, level_slug: str,
+              answers: list[str], assignment_id: int | None = None):
+    return _json_or_raise(_req("POST", "/agent/coach_or_celebrate",
+                               json={"student_id": student_id, "lesson_id": lesson_id, "level_slug": level_slug,
+                                     "answers": answers, "assignment_id": assignment_id}))
+
+# ---- Auth ----
+def login(email: str, password: str):
+    return _json_or_raise(_req("POST", "/auth/login", json={"email": email, "password": password}))
 
-def record_budget_builder_play(user_id: int, weekly_allowance: int, allocations: List[Dict[str, Any]], gained_xp: Optional[int] = None) -> Dict[str, Any]:
-    payload = {"user_id": user_id, "weekly_allowance": weekly_allowance, "allocations": allocations}
-    if gained_xp is not None:
-        payload["gained_xp"] = int(gained_xp)
-    return _json_or_raise(_req("POST", "/games/budget_builder/record", json=payload))
+def signup_student(name: str, email: str, password: str, level_label: str, country_label: str):
+    payload_student = {
+        "name": name, "email": email, "password": password,
+        "level_label": level_label, "country_label": country_label
+    }
+    return _try_candidates("POST", [
+        ("/auth/signup/student", {"json": payload_student}),
+        ("/auth/register", {"json": {
+            "role": "student", "name": name, "email": email, "password": password,
+            "level": level_label, "country": country_label
+        }}),
+    ])
+
+def signup_teacher(title: str, name: str, email: str, password: str):
+    payload_teacher = {"title": title, "name": name, "email": email, "password": password}
+    return _try_candidates("POST", [
+        ("/auth/signup/teacher", {"json": payload_teacher}),
+        ("/auth/register", {"json": {
+            "role": "teacher", "title": title, "name": name, "email": email, "password": password
+        }}),
+    ])
+
+# ---- New LangGraph-backed endpoints ----
+def fetch_lesson_content(lesson: str, module: str, topic: str):
+    r = _json_or_raise(_req("POST", "/lesson",
+                            json={"lesson": lesson, "module": module, "topic": topic}))
+    return r["lesson_content"]
+
+def submit_lesson_quiz(lesson: str, module: str, topic: str, responses: dict):
+    return _json_or_raise(_req("POST", "/lesson-quiz",
+                               json={"lesson": lesson, "module": module, "topic": topic, "responses": responses}))
+
+def submit_practice_quiz(lesson: str, responses: dict):
+    return _json_or_raise(_req("POST", "/practice-quiz",
+                               json={"lesson": lesson, "responses": responses}))
+
+def send_to_chatbot(messages: list[dict]):
+    return _json_or_raise(_req("POST", "/chatbot", json={"messages": messages}))
+
+# --- Game API helpers ---
+def record_money_match_play(user_id: int, target: int, total: int,
+                            elapsed_ms: int, matched: bool, gained_xp: int):
+    payload = {
+        "user_id": user_id, "target": target, "total": total,
+        "elapsed_ms": elapsed_ms, "matched": matched, "gained_xp": gained_xp,
+    }
+    return _try_candidates("POST", [
+        ("/games/money_match/record", {"json": payload}),
+    ])
 
-def record_debt_dilemma_play(user_id: int, level: int, round_no: int, wallet: int, health: int, happiness: int, credit_score: int, event_json: Dict[str, Any], outcome: str, gained_xp: Optional[int] = None) -> Dict[str, Any]:
+def record_budget_builder_play(user_id: int, weekly_allowance: int, budget_score: int,
+                               elapsed_ms: int, allocations: list[dict], gained_xp: int | None):
     payload = {
-        "user_id": user_id, "level": level, "round_no": round_no, "wallet": wallet,
-        "health": health, "happiness": happiness, "credit_score": credit_score,
-        "event_json": event_json, "outcome": outcome,
+        "user_id": user_id,
+        "weekly_allowance": weekly_allowance,
+        "budget_score": budget_score,
+        "elapsed_ms": elapsed_ms,
+        "allocations": allocations,
+        "gained_xp": gained_xp,
     }
-    if gained_xp is not None:
-        payload["gained_xp"] = int(gained_xp)
-    return _json_or_raise(_req("POST", "/games/debt_dilemma/record", json=payload))
+    return _try_candidates("POST", [
+        ("/games/budget_builder/record", {"json": payload}),
+    ])
 
-def record_profit_puzzler_play(user_id: int, scenario_id: str, title: str, units: int, price: int, cost: int, user_answer: float, actual_profit: float, is_correct: bool, gained_xp: Optional[int] = None) -> Dict[str, Any]:
+def record_debt_dilemma_play(user_id: int, loans_cleared: int,
+                             mistakes: int, elapsed_ms: int, gained_xp: int):
     payload = {
-        "user_id": user_id, "scenario_id": scenario_id, "title": title, "units": units,
-        "price": price, "cost": cost, "user_answer": user_answer, "actual_profit": actual_profit,
-        "is_correct": is_correct,
+        "user_id": user_id,
+        "loans_cleared": loans_cleared,
+        "mistakes": mistakes,
+        "elapsed_ms": elapsed_ms,
+        "gained_xp": gained_xp,
     }
-    if gained_xp is not None:
-        payload["gained_xp"] = int(gained_xp)
-    return _json_or_raise(_req("POST", "/games/profit_puzzler/record", json=payload))
+    return _try_candidates("POST", [
+        ("/games/debt_dilemma/record", {"json": payload}),
+    ])
 
-# ----------------------------------------------------------------------------
-# Utilities
-# ----------------------------------------------------------------------------
+def record_profit_puzzler_play(user_id: int, puzzles_solved: int, mistakes: int, elapsed_ms: int, gained_xp: int | None = None):
+    payload = {"user_id": user_id, "puzzles_solved": puzzles_solved, "mistakes": mistakes, "elapsed_ms": elapsed_ms}
+    if gained_xp is not None:
+        payload["gained_xp"] = gained_xp
+    return _try_candidates("POST", [("/games/profit_puzzler/record", {"json": payload})])
 
-def level_from_xp(xp: int) -> int:
-    d = _json_or_raise(_req("GET", "/level-from-xp", params={"xp": int(xp)}))
-    return int(d.get("level", 1))
+# --- Tutor Explanation ---
+def tutor_explain(lesson_id: int, level_slug: str, wrong: list[dict]):
+    payload = {
+        "lesson_id": lesson_id,
+        "level_slug": level_slug,
+        "wrong": wrong
+    }
+    return _json_or_raise(_req("POST", "/tutor/explain", json=payload, timeout=60))