elkay: api.py, chatbot

phase/Student_view/chatbot.py

@@ -1,104 +1,28 @@
 # phase/Student_view/chatbot.py
 import streamlit as st
-import datetime, os, traceback
-from huggingface_hub import InferenceClient
-
-HF_TOKEN = os.getenv("HF_TOKEN")
-GEN_MODEL = os.getenv("GEN_MODEL", "TinyLlama/TinyLlama-1.1B-Chat-v1.0")  # <- default TinyLlama
-
-if not HF_TOKEN:
-    st.error("⚠️ HF_TOKEN is not set. In your Space, add a Secret named HF_TOKEN.")
-else:
-    client = InferenceClient(model=GEN_MODEL, token=HF_TOKEN, timeout=60)
+import datetime, traceback
+from typing import List, Dict
+import utils.api as api  # <-- use backend
 
 TUTOR_PROMPT = (
     "You are a kind Jamaican primary-school finance tutor. "
     "Keep answers short, friendly, and age-appropriate. "
-    "Teach step-by-step with tiny examples. Avoid giving personal financial advice."
+    "Teach step-by-step with tiny examples. Avoid giving personal financial advice. "
+    "Ensure the explanations are based on the Jamaican context and currency (JMD). "
+    "If you don't know the answer, just say you don't know."
 )
 
-
-
-# -------------------------------
-# History helpers
-# -------------------------------
-def _format_history_for_flan(messages: list[dict]) -> str:
-    """Format history for text-generation style models."""
-    lines = []
-    for m in messages:
-        txt = (m.get("text") or "").strip()
-        if not txt:
-            continue
-        lines.append(("Tutor" if m.get("sender") == "assistant" else "User") + f": {txt}")
-    return "\n".join(lines)
-
-def _history_as_chat_messages(messages: list[dict]) -> list[dict]:
-    """Convert history to chat-completion style messages."""
+def _history_for_backend(messages: List[Dict]) -> List[Dict[str, str]]:
+    # Convert local history to backend chat format
     msgs = [{"role": "system", "content": TUTOR_PROMPT}]
     for m in messages:
         txt = (m.get("text") or "").strip()
         if not txt:
             continue
-        role = "assistant" if m.get("sender") == "assistant" else "user"
+        role = "assistant" if (m.get("sender") == "assistant") else "user"
         msgs.append({"role": role, "content": txt})
     return msgs
 
-def _extract_chat_text(chat_resp) -> str:
-    """Extract text from HF chat response."""
-    try:
-        return chat_resp.choices[0].message["content"] if isinstance(
-            chat_resp.choices[0].message, dict
-        ) else chat_resp.choices[0].message.content
-    except Exception:
-        try:
-            return chat_resp["choices"][0]["message"]["content"]
-        except Exception:
-            return str(chat_resp)
-
-# -------------------------------
-# Reply logic
-# -------------------------------
-def _reply_with_hf():
-    if "client" not in globals():
-        raise RuntimeError("HF client not initialized")
-
-    try:
-        # 1) Prefer chat API
-        msgs = _history_as_chat_messages(st.session_state.get("messages", []))
-        chat = client.chat.completions.create(
-            model=GEN_MODEL,
-            messages=msgs,
-            max_tokens=300,   # give enough room
-            temperature=0.2,
-            top_p=0.9,
-        )
-        return _extract_chat_text(chat).strip()
-
-    except ValueError as ve:
-        # 2) Fallback to text-generation if chat unsupported
-        if "Supported task: text-generation" in str(ve):
-            convo = _format_history_for_flan(st.session_state.get("messages", []))
-            tg_prompt = f"{TUTOR_PROMPT}\n\n{convo}\n\nTutor:"
-            resp = client.text_generation(
-                tg_prompt,
-                max_new_tokens=300,
-                temperature=0.2,
-                top_p=0.9,
-                repetition_penalty=1.1,
-                return_full_text=True,
-                stream=False,
-            )
-            return (resp.get("generated_text") if isinstance(resp, dict) else resp).strip()
-
-        raise  # rethrow anything else
-
-    except Exception as e:
-        err_text = ''.join(traceback.format_exception_only(type(e), e)).strip()
-        raise RuntimeError(f"Hugging Face API Error: {err_text}")
-
-# -------------------------------
-# Session message helper
-# -------------------------------
 def add_message(text: str, sender: str):
     if "messages" not in st.session_state:
         st.session_state.messages = []
@@ -114,20 +38,16 @@ def add_message(text: str, sender: str):
 def _coerce_ts(ts):
     if isinstance(ts, datetime.datetime):
         return ts
-    if isinstance(ts, (int, float)):
-        try:
+    try:
+        if isinstance(ts, (int, float)):
             return datetime.datetime.fromtimestamp(ts)
-        except Exception:
-            return None
-    if isinstance(ts, str):
-        # Try ISO 8601 first; fall back to float epoch
-        try:
-            return datetime.datetime.fromisoformat(ts)
-        except Exception:
+        if isinstance(ts, str):
             try:
-                return datetime.datetime.fromtimestamp(float(ts))
+                return datetime.datetime.fromisoformat(ts)
             except Exception:
-                return None
+                return datetime.datetime.fromtimestamp(float(ts))
+    except Exception:
+        return None
     return None
 
 def _normalize_messages():
@@ -141,10 +61,17 @@ def _normalize_messages():
         normed.append({**m, "text": text, "sender": sender, "timestamp": ts})
     st.session_state.messages = normed
 
+def _reply_with_backend():
+    # Identify context — if your app tracks current lesson/level in session, use it here
+    lesson_id = st.session_state.get("current_lesson_id", 0)
+    level_slug = st.session_state.get("current_level_slug", "beginner")
+
+    user_query = st.session_state.messages[-1]["text"]
+    history = _history_for_backend(st.session_state.get("messages", []))
+
+    # Let backend do retrieval + chat generation
+    return api.chat_ai(user_query, lesson_id=lesson_id, level_slug=level_slug, history=history)
 
-# -------------------------------
-# Streamlit page
-# -------------------------------
 def show_page():
     st.title("🤖 AI Financial Tutor")
     st.caption("Get personalized help with your financial questions")
@@ -160,7 +87,7 @@ def show_page():
         st.session_state.is_typing = False
 
     _normalize_messages()
-    
+
     chat_container = st.container()
     with chat_container:
         for msg in st.session_state.messages:
@@ -174,7 +101,6 @@ def show_page():
             )
             st.markdown(bubble, unsafe_allow_html=True)
 
-
         if st.session_state.is_typing:
             st.markdown("🤖 _FinanceBot is typing..._")
 
@@ -188,7 +114,7 @@ def show_page():
             "How do I start investing?"
         ]
         for i, q in enumerate(quick):
-            if cols[i % 2].button(q):
+            if cols[i % 2].button(q, key=f"quick_{i}"):
                 add_message(q, "user")
                 st.session_state.is_typing = True
                 st.rerun()
@@ -202,7 +128,7 @@ def show_page():
     if st.session_state.is_typing:
         try:
             with st.spinner("FinanceBot is thinking..."):
-                bot_reply = _reply_with_hf()
+                bot_reply = _reply_with_backend()
                 add_message(bot_reply, "assistant")
         except Exception as e:
             add_message(f"⚠️ Error: {e}", "assistant")

utils/api.py

@@ -1,20 +1,29 @@
-import os, json, requests, logging
+"""
+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
 from urllib3.util.retry import Retry
 from requests.adapters import HTTPAdapter
 
-# ---- Setup ----
+# ----------------------------------------------------------------------------
+# Config & session
+# ----------------------------------------------------------------------------
 BACKEND = (os.getenv("BACKEND_URL") or "").strip().rstrip("/")
 if not BACKEND:
     raise RuntimeError("BACKEND_URL is not set in Space secrets.")
 
 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,
@@ -22,9 +31,8 @@ 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)",
@@ -32,482 +40,302 @@ _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'}:\n{snippet}")
+        raise RuntimeError(f"Expected JSON but got {ctype or 'unknown'}: {snippet}")
 
-def _req(method: str, path: str, **kw):
+def _req(method: str, path: str, **kw) -> requests.Response:
     if not path.startswith("/"):
         path = "/" + path
     url = f"{BACKEND}{path}"
     kw.setdefault("timeout", DEFAULT_TIMEOUT)
-    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
+    return _session.request(method, url, **kw)
 
-# ---- 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))
-
-# -- 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"))
+# ----------------------------------------------------------------------------
+# Health
+# ----------------------------------------------------------------------------
 
-def level_from_xp(xp: int):
-    return _json_or_raise(_req("GET", "/levels/from_xp", params={"xp": xp}))["level"]
+def health() -> Dict[str, Any]:
+    return _json_or_raise(_req("GET", "/health"))  # should return local_model, embedding_model
 
-# -- 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)
+# ----------------------------------------------------------------------------
+# RAG + Chat
+# ----------------------------------------------------------------------------
 
-def list_classes_for_student(student_id: int):
-    return _json_or_raise(_req("GET", f"/students/{student_id}/classes"))
+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", ""))
 
-def class_content_counts(class_id: int):
-    return _try_candidates("GET", [
-        (f"/classes/{class_id}/content_counts", {}),
-        (f"/classes/{class_id}/counts", {}),
-    ])
+def chat_ai(query: str, lesson_id: int, level_slug: str, history: Optional[List[Dict[str, str]]] = None) -> str:
+    payload = {
+        "query": query,
+        "lesson_id": int(lesson_id) if lesson_id is not None else 0,
+        "level_slug": level_slug or "beginner",
+        "history": history or [],
+    }
+    data = _json_or_raise(_req("POST", "/chat", json=payload, timeout=90))
+    return str(data.get("answer", ""))
 
-def student_class_progress(student_id: int, class_id: int):
-    return _json_or_raise(_req("GET", f"/classes/{class_id}/students/{student_id}/progress"))
+# ----------------------------------------------------------------------------
+# Auth
+# ----------------------------------------------------------------------------
 
-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 login(email: str, password: str) -> Dict[str, Any]:
+    return _json_or_raise(_req("POST", "/auth/login", json={"email": email, "password": password}))
 
-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 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))
 
-# ---------- 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 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 list_classes_by_teacher(teacher_id: int):
-    return _try_candidates("GET", [
-        (f"/teachers/{teacher_id}/classes", {}),
-    ])
+# ----------------------------------------------------------------------------
+# Classes
+# ----------------------------------------------------------------------------
 
-def list_students_in_class(class_id: int):
+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 list_classes_by_teacher(teacher_id: int) -> List[Dict[str, Any]]:
+    return _json_or_raise(_req("GET", f"/teachers/{teacher_id}/classes"))
+
+def list_students_in_class(class_id: int) -> List[Dict[str, Any]]:
     return _json_or_raise(_req("GET", f"/classes/{class_id}/students"))
 
-def class_content_counts(class_id: int):
-    return _try_candidates("GET", [
-        (f"/classes/{class_id}/content_counts", {}),
-        (f"/classes/{class_id}/counts", {}),
-    ])
+def class_content_counts(class_id: int) -> Dict[str, Any]:
+    return _json_or_raise(_req("GET", f"/classes/{class_id}/content_counts"))
 
-def list_class_assignments(class_id: int):
+def list_class_assignments(class_id: int) -> List[Dict[str, Any]]:
     return _json_or_raise(_req("GET", f"/classes/{class_id}/assignments"))
 
-def class_analytics(class_id: int):
+def class_analytics(class_id: int) -> Dict[str, Any]:
     return _json_or_raise(_req("GET", f"/classes/{class_id}/analytics"))
 
-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 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 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):
+# ----------------------------------------------------------------------------
+
+def list_lessons_by_teacher(teacher_id: int) -> List[Dict[str, Any]]:
     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]):
-    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 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 get_lesson(lesson_id: int):
+def get_lesson(lesson_id: int) -> Dict[str, Any]:
     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]):
-    d = _req("PUT", f"/lessons/{lesson_id}", json={
-        "teacher_id": teacher_id,
-        "title": title,
-        "description": description,
-        "subject": subject,
-        "level": level,
-        "sections": sections
-    }).json()
+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,
+    }))
     return bool(d.get("ok", True))
 
-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", "")
+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"))
+
+# ----------------------------------------------------------------------------
 # Quizzes
-def list_quizzes_by_teacher(teacher_id: int):
+# ----------------------------------------------------------------------------
+
+def list_quizzes_by_teacher(teacher_id: int) -> List[Dict[str, Any]]:
     return _json_or_raise(_req("GET", f"/teachers/{teacher_id}/quizzes"))
 
-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 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 mark_assignment_started(student_id: int, assignment_id: int):
-    return _req("POST",
-                f"/assignments/{assignment_id}/start",
-                json={"student_id": student_id}).json()
+def get_quiz(quiz_id: int) -> Dict[str, Any]:
+    return _json_or_raise(_req("GET", f"/quizzes/{quiz_id}"))
 
-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 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 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 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 list_assigned_students_for_quiz(quiz_id: int) -> List[Dict[str, Any]]:
+    return _json_or_raise(_req("GET", f"/quizzes/{quiz_id}/assignees"))
+
+# Backend-side auto quiz generation from lesson chunks
+
+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 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}
-    """
+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]:
     payload = {
-        "lesson_id": int(lesson_id) if lesson_id is not None else None,
+        "student_id": student_id,
+        "lesson_id": lesson_id,
         "level_slug": level_slug,
         "user_answers": user_answers,
         "original_quiz": original_quiz,
+        "assignment_id": assignment_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))
+    return _json_or_raise(_req("POST", "/quiz/grade", json=payload, timeout=90))
 
-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", "")
+# Tutor explanation bullets for wrong answers
 
-def list_assigned_students_for_lesson(lesson_id: int):
-    return _json_or_raise(_req("GET", f"/lessons/{lesson_id}/assignees"))
+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
+    }))
 
-def list_assigned_students_for_quiz(quiz_id: int):
-    return _json_or_raise(_req("GET", f"/quizzes/{quiz_id}/assignees"))
+# ----------------------------------------------------------------------------
+# Assignments & Progress
+# ----------------------------------------------------------------------------
 
-# 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 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,
+    }))
 
-# ---------- 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 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 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}")
+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,
+    }))
+
+# ----------------------------------------------------------------------------
+# Student dashboard
+# ----------------------------------------------------------------------------
+
+def user_stats(student_id: int) -> Dict[str, Any]:
+    return _json_or_raise(_req("GET", f"/students/{student_id}/stats"))
+
+def list_assignments_for_student(student_id: int) -> List[Dict[str, Any]]:
+    return _json_or_raise(_req("GET", f"/students/{student_id}/assignments"))
+
+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
     try:
-        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}))
+        return int(round(float(str(v).strip().rstrip("%"))))
+    except Exception:
+        return 0
 
-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 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 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,
-        "weekly_allowance": weekly_allowance,
-        "budget_score": budget_score,
-        "elapsed_ms": elapsed_ms,
-        "allocations": allocations,
-        "gained_xp": gained_xp,
-    }
-    return _try_candidates("POST", [
-        ("/games/budget_builder/record", {"json": payload}),
-    ])
+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))
+
+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 record_debt_dilemma_play(user_id: int, loans_cleared: int,
-                             mistakes: int, elapsed_ms: int, gained_xp: int):
+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]:
     payload = {
-        "user_id": user_id,
-        "loans_cleared": loans_cleared,
-        "mistakes": mistakes,
-        "elapsed_ms": elapsed_ms,
-        "gained_xp": gained_xp,
+        "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,
     }
-    return _try_candidates("POST", [
-        ("/games/debt_dilemma/record", {"json": payload}),
-    ])
-
-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})])
+        payload["gained_xp"] = int(gained_xp)
+    return _json_or_raise(_req("POST", "/games/debt_dilemma/record", json=payload))
 
-# --- Tutor Explanation ---
-def tutor_explain(lesson_id: int, level_slug: str, wrong: list[dict]):
+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]:
     payload = {
-        "lesson_id": lesson_id,
-        "level_slug": level_slug,
-        "wrong": wrong
+        "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,
     }
-    return _json_or_raise(_req("POST", "/tutor/explain", json=payload, timeout=60))
+    if gained_xp is not None:
+        payload["gained_xp"] = int(gained_xp)
+    return _json_or_raise(_req("POST", "/games/profit_puzzler/record", json=payload))
+
+# ----------------------------------------------------------------------------
+# Utilities
+# ----------------------------------------------------------------------------
+
+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))