Update main.py

main.py

@@ -68,8 +68,8 @@ except Exception as e:
     logger.error(f"FATAL GenAI init: {e}")
     raise SystemExit(1)
 
-TEXT_MODEL       = "gemini-2.5-flash"
-MULTIMODAL_MODEL = "gemini-2.5-flash"
+TEXT_MODEL       = "gemini-3.1-flash-lite-preview"
+MULTIMODAL_MODEL = "gemini-3.1-flash-lite-preview"
 
 DEEPGRAM_API_KEY   = os.environ.get("DEEPGRAM_API_KEY")
 ELEVENLABS_API_KEY = os.environ.get("ELEVENLABS_API_KEY")
@@ -1803,6 +1803,801 @@ def debug_data_api():
 
     return jsonify(results)
 
+
+# =============================================================================
+# 18. FEEDBACK SYSTEM
+# Any role can submit feedback on any screen. Admins read it all.
+# =============================================================================
+
+@app.route("/api/feedback/submit", methods=["POST"])
+def submit_feedback():
+    """
+    Submit feedback from any screen.
+    Body: { screen, rating (1-5), message, role, context (optional) }
+    """
+    uid = verify_token(request.headers.get("Authorization"))
+    if not uid:
+        return jsonify({"error": "Unauthorized"}), 401
+
+    data    = request.get_json() or {}
+    screen  = data.get("screen", "unknown")
+    rating  = data.get("rating")           # 1-5 stars
+    message = data.get("message", "")
+    context = data.get("context", {})      # e.g. { subjectId, nodeId, quizId }
+
+    user    = get_user(uid)
+    role    = user.get("role", "unknown")
+
+    if not message and not rating:
+        return jsonify({"error": "rating or message required"}), 400
+
+    fid = uuid.uuid4().hex
+    doc = {
+        "feedbackId":  fid,
+        "userId":      uid,
+        "displayName": user.get("displayName"),
+        "email":       user.get("email"),
+        "role":        role,
+        "screen":      screen,
+        "rating":      rating,
+        "message":     message,
+        "context":     context,
+        "createdAt":   datetime.utcnow().isoformat(),
+        "status":      "unread",
+    }
+    db_ref.child(f"feedback/{fid}").set(doc)
+    # Also index by screen for easy admin queries
+    db_ref.child(f"feedback_by_screen/{screen}/{fid}").set(True)
+    return jsonify({"success": True, "feedbackId": fid}), 201
+
+
+@app.route("/api/admin/feedback", methods=["GET"])
+def admin_list_feedback():
+    """
+    Admin reads all feedback.
+    Query: screen (filter), role (filter), status (unread/read/all), limit (default 50)
+    """
+    uid = verify_token(request.headers.get("Authorization"))
+    if not uid:
+        return jsonify({"error": "Unauthorized"}), 401
+    try:
+        require_role(uid, ["admin"])
+    except PermissionError as e:
+        return jsonify({"error": str(e)}), 403
+
+    screen_f = request.args.get("screen")
+    role_f   = request.args.get("role")
+    status_f = request.args.get("status", "all")
+    limit    = int(request.args.get("limit", 50))
+
+    all_fb   = db_ref.child("feedback").get() or {}
+    result   = []
+    for fid, item in all_fb.items():
+        if not item: continue
+        if screen_f and item.get("screen") != screen_f: continue
+        if role_f   and item.get("role")   != role_f:   continue
+        if status_f != "all" and item.get("status") != status_f: continue
+        result.append(item)
+
+    result.sort(key=lambda x: x.get("createdAt", ""), reverse=True)
+    return jsonify(result[:limit])
+
+
+@app.route("/api/admin/feedback/<feedback_id>/mark-read", methods=["POST"])
+def mark_feedback_read(feedback_id):
+    uid = verify_token(request.headers.get("Authorization"))
+    if not uid: return jsonify({"error": "Unauthorized"}), 401
+    try: require_role(uid, ["admin"])
+    except PermissionError as e: return jsonify({"error": str(e)}), 403
+    db_ref.child(f"feedback/{feedback_id}").update({"status": "read", "readBy": uid,
+                                                    "readAt": datetime.utcnow().isoformat()})
+    return jsonify({"success": True})
+
+
+# =============================================================================
+# 19. REPORTING — LEARNER DASHBOARD
+# =============================================================================
+
+@app.route("/api/reports/learner/summary", methods=["GET"])
+def learner_report_summary():
+    """
+    Full personal report for the logged-in learner.
+    Returns structured data + AI-generated narrative insight.
+    """
+    uid = verify_token(request.headers.get("Authorization"))
+    if not uid: return jsonify({"error": "Unauthorized"}), 401
+
+    attempts  = db_ref.child("attempts").get() or {}
+    my_atts   = sorted([a for a in attempts.values() if a.get("userId") == uid],
+                       key=lambda x: x.get("createdAt", ""))
+    sessions  = db_ref.child("revision_sessions").get() or {}
+    my_sess   = [s for s in sessions.values() if s.get("userId") == uid]
+    subjects  = db_ref.child("subjects").get() or {}
+    topics    = db_ref.child("topics").get() or {}
+
+    # Progress trend: last 14 attempts
+    trend = [{"date": a.get("createdAt","")[:10], "percentage": round(a.get("percentage",0),1),
+              "subject": subjects.get(a.get("subjectId",""),{}).get("name","?")}
+             for a in my_atts[-14:]]
+
+    # Aggregate per subject
+    subj_stats, topic_stats = _aggregate_attempts(my_atts)
+    strong_topics = sorted(
+        [{"topicId": t, "name": topics.get(t,{}).get("name",t),
+          "percentage": round((s["correct"]/s["total"])*100,1)}
+         for t, s in topic_stats.items() if s["total"] >= 3],
+        key=lambda x: -x["percentage"]
+    )[:5]
+    weak_topics = sorted(
+        [{"topicId": t, "name": topics.get(t,{}).get("name",t),
+          "percentage": round((s["correct"]/s["total"])*100,1)}
+         for t, s in topic_stats.items() if s["total"] >= 3],
+        key=lambda x: x["percentage"]
+    )[:5]
+
+    # Learning path completion per subject
+    path_progress = db_ref.child(f"users/{uid}/path_progress").get() or {}
+    path_summary  = {sid: len(nodes) for sid, nodes in path_progress.items()
+                     if isinstance(nodes, dict)}
+
+    # AI narrative
+    payload = {
+        "totalAttempts": len(my_atts),
+        "recentTrend": trend,
+        "strongTopics": strong_topics,
+        "weakTopics": weak_topics,
+        "revisionSessions": len(my_sess),
+        "pathProgress": path_summary,
+    }
+    ai_prompt = f"""
+You are a supportive academic coach for a Zimbabwean secondary school student.
+
+Here is the student's learning data (JSON):
+{json.dumps(payload, ensure_ascii=False)[:4000]}
+
+Write a personalised progress report in a warm, encouraging tone. Structure:
+1. HEADLINE (one sentence — their overall trajectory)
+2. STRENGTHS (what they are doing well, specific topics)
+3. FOCUS AREAS (where to spend time next, constructive)
+4. RECOMMENDED NEXT STEPS (2-3 specific, actionable suggestions)
+5. MOTIVATIONAL CLOSE (one sentence)
+
+Keep it concise, honest, and motivating. Address the student directly as "you".
+"""
+    narrative = send_gemini_text(ai_prompt)
+
+    return jsonify({
+        "totalAttempts":    len(my_atts),
+        "revisionSessions": len(my_sess),
+        "recentTrend":      trend,
+        "strongTopics":     strong_topics,
+        "weakTopics":       weak_topics,
+        "pathProgress":     path_summary,
+        "aiNarrative":      narrative,
+        "generatedAt":      datetime.utcnow().isoformat(),
+    })
+
+
+# =============================================================================
+# 20. REPORTING — TEACHER DASHBOARD
+# =============================================================================
+
+@app.route("/api/reports/teacher/class/<class_id>", methods=["GET"])
+def teacher_class_report(class_id):
+    """
+    Full class report for a teacher — analytics + AI narrative insights.
+    """
+    uid = verify_token(request.headers.get("Authorization"))
+    if not uid: return jsonify({"error": "Unauthorized"}), 401
+    try: require_role(uid, ["teacher","admin"])
+    except PermissionError as e: return jsonify({"error": str(e)}), 403
+    try: require_approved(uid)
+    except PermissionError as e: return jsonify({"error": str(e)}), 403
+
+    class_doc = db_ref.child(f"classes/{class_id}").get()
+    if not class_doc or class_doc.get("teacherId") != uid:
+        return jsonify({"error": "Class not found or access denied"}), 404
+
+    learner_ids = set(class_doc.get("learnerIds") or [])
+    attempts    = db_ref.child("attempts").get() or {}
+    class_atts  = [a for a in attempts.values() if a.get("userId") in learner_ids]
+
+    subjects    = db_ref.child("subjects").get() or {}
+    topics      = db_ref.child("topics").get() or {}
+    users       = db_ref.child("users").get() or {}
+
+    # Per-learner summary
+    learner_stats = {}
+    for a in class_atts:
+        lid = a.get("userId")
+        if not lid: continue
+        learner_stats.setdefault(lid, {"attempts": 0, "scoreSum": 0, "totalSum": 0, "wrongQ": []})
+        learner_stats[lid]["attempts"]  += 1
+        learner_stats[lid]["scoreSum"]  += a.get("score", 0)
+        learner_stats[lid]["totalSum"]  += a.get("total", 0)
+        learner_stats[lid]["wrongQ"]    += a.get("wrongQuestions", [])
+
+    learner_rows = []
+    for lid, s in learner_stats.items():
+        avg = round((s["scoreSum"]/s["totalSum"])*100, 1) if s["totalSum"] else 0
+        u   = users.get(lid, {})
+        learner_rows.append({
+            "uid": lid, "name": u.get("displayName","?"), "email": u.get("email",""),
+            "attempts": s["attempts"], "averagePercentage": avg,
+        })
+    learner_rows.sort(key=lambda x: -x["averagePercentage"])
+
+    top_learners     = learner_rows[:5]
+    struggling       = [l for l in learner_rows if l["averagePercentage"] < 50]
+
+    # Topic weakness map
+    _, topic_stats   = _aggregate_attempts(class_atts)
+    weak_class_topics= sorted(
+        [{"topicId": t, "name": topics.get(t,{}).get("name",t),
+          "percentage": round((s["correct"]/s["total"])*100,1), "attempts": s["total"]}
+         for t, s in topic_stats.items() if s["total"] >= 5],
+        key=lambda x: x["percentage"]
+    )[:8]
+
+    # Subject breakdown
+    subj_stats, _ = _aggregate_attempts(class_atts)
+    subj_rows = [{"subjectId": sid, "name": subjects.get(sid,{}).get("name",sid),
+                  "attempts": s["attempts"],
+                  "averagePercentage": round((s["scoreSum"]/s["totalSum"])*100,1) if s["totalSum"] else 0}
+                 for sid, s in subj_stats.items()]
+
+    payload = {
+        "className": class_doc.get("name"),
+        "totalLearners": len(learner_ids),
+        "activeLearners": len(learner_stats),
+        "totalAttempts": len(class_atts),
+        "topLearners": top_learners,
+        "strugglingLearners": struggling[:5],
+        "weakClassTopics": weak_class_topics,
+        "subjectBreakdown": subj_rows,
+    }
+
+    ai_prompt = f"""
+You are an expert education analyst advising a teacher in Zimbabwe.
+
+Here is the class performance data (JSON):
+{json.dumps(payload, ensure_ascii=False)[:5000]}
+
+Write a professional class performance report. Structure:
+1. CLASS OVERVIEW (overall performance level, engagement rate)
+2. TOP PERFORMERS (names and what they are doing well)
+3. STUDENTS NEEDING SUPPORT (constructive, non-stigmatising)
+4. CURRICULUM GAPS (which topics are most problematic across the class)
+5. TEACHING RECOMMENDATIONS (3-4 specific pedagogical suggestions)
+6. PRIORITISED ACTION LIST (bullet points, most urgent first)
+
+Tone: professional, data-driven, constructive. Address the teacher as "your class".
+"""
+    narrative = send_gemini_text(ai_prompt)
+
+    return jsonify({
+        **payload,
+        "aiNarrative":  narrative,
+        "generatedAt":  datetime.utcnow().isoformat(),
+    })
+
+
+@app.route("/api/reports/teacher/summary", methods=["GET"])
+def teacher_summary_report():
+    """
+    Aggregate report across ALL classes a teacher owns.
+    """
+    uid = verify_token(request.headers.get("Authorization"))
+    if not uid: return jsonify({"error": "Unauthorized"}), 401
+    try: require_role(uid, ["teacher","admin"])
+    except PermissionError as e: return jsonify({"error": str(e)}), 403
+    try: require_approved(uid)
+    except PermissionError as e: return jsonify({"error": str(e)}), 403
+
+    classes     = db_ref.child("classes").get() or {}
+    my_classes  = [c for c in classes.values() if c.get("teacherId") == uid]
+    all_lids    = set()
+    for c in my_classes:
+        all_lids.update(c.get("learnerIds") or [])
+
+    attempts    = db_ref.child("attempts").get() or {}
+    my_atts     = [a for a in attempts.values() if a.get("userId") in all_lids]
+    topics      = db_ref.child("topics").get() or {}
+    subjects    = db_ref.child("subjects").get() or {}
+
+    _, topic_stats = _aggregate_attempts(my_atts)
+    subj_stats, _  = _aggregate_attempts(my_atts)
+
+    weak_topics = sorted(
+        [{"name": topics.get(t,{}).get("name",t),
+          "percentage": round((s["correct"]/s["total"])*100,1)}
+         for t, s in topic_stats.items() if s["total"] >= 5],
+        key=lambda x: x["percentage"]
+    )[:10]
+
+    summary = {
+        "totalClasses":    len(my_classes),
+        "totalLearners":   len(all_lids),
+        "totalAttempts":   len(my_atts),
+        "weakTopics":      weak_topics,
+        "subjectBreakdown":[{"name": subjects.get(sid,{}).get("name",sid),
+                             "averagePercentage": round((s["scoreSum"]/s["totalSum"])*100,1) if s["totalSum"] else 0}
+                            for sid, s in subj_stats.items()],
+    }
+
+    ai_prompt = f"""
+You are an education coach reviewing a teacher's overall performance data across all their classes.
+
+Data: {json.dumps(summary, ensure_ascii=False)[:4000]}
+
+Write a concise teaching effectiveness summary:
+1. OVERALL IMPACT (breadth and quality of student engagement)
+2. CURRICULUM COVERAGE ANALYSIS
+3. AREAS FOR PROFESSIONAL DEVELOPMENT
+4. COMMENDATIONS
+
+Professional tone. Address teacher directly.
+"""
+    return jsonify({**summary, "aiNarrative": send_gemini_text(ai_prompt),
+                   "generatedAt": datetime.utcnow().isoformat()})
+
+
+# =============================================================================
+# 21. REPORTING — PARENT DASHBOARD
+# =============================================================================
+
+@app.route("/api/reports/parent/learner/<learner_id>", methods=["GET"])
+def parent_learner_report(learner_id):
+    """
+    Full parent-facing report on a linked learner — AI narrative included.
+    """
+    uid = verify_token(request.headers.get("Authorization"))
+    if not uid: return jsonify({"error": "Unauthorized"}), 401
+    try: require_role(uid, ["parent","admin"])
+    except PermissionError as e: return jsonify({"error": str(e)}), 403
+    try: require_approved(uid)
+    except PermissionError as e: return jsonify({"error": str(e)}), 403
+
+    parent = get_user(uid)
+    if learner_id not in (parent.get("linkedLearnerIds") or []) and parent.get("role") != "admin":
+        return jsonify({"error": "Learner not linked to your account"}), 403
+
+    learner   = get_user(learner_id)
+    attempts  = db_ref.child("attempts").get() or {}
+    l_atts    = sorted([a for a in attempts.values() if a.get("userId") == learner_id],
+                       key=lambda x: x.get("createdAt",""))
+    subjects  = db_ref.child("subjects").get() or {}
+    topics    = db_ref.child("topics").get() or {}
+
+    subj_stats, topic_stats = _aggregate_attempts(l_atts)
+    trend = [{"date": a.get("createdAt","")[:10],
+              "percentage": round(a.get("percentage",0),1)}
+             for a in l_atts[-14:]]
+
+    strong = sorted(
+        [{"name": topics.get(t,{}).get("name",t),
+          "percentage": round((s["correct"]/s["total"])*100,1)}
+         for t, s in topic_stats.items() if s["total"] >= 3],
+        key=lambda x: -x["percentage"]
+    )[:5]
+    weak = sorted(
+        [{"name": topics.get(t,{}).get("name",t),
+          "percentage": round((s["correct"]/s["total"])*100,1)}
+         for t, s in topic_stats.items() if s["total"] >= 3],
+        key=lambda x: x["percentage"]
+    )[:5]
+
+    recent_activity = [
+        {"date": a.get("createdAt","")[:10],
+         "subject": subjects.get(a.get("subjectId",""),{}).get("name","?"),
+         "score": f"{a.get('score',0)}/{a.get('total',0)}",
+         "percentage": round(a.get("percentage",0),1)}
+        for a in l_atts[-7:]
+    ]
+
+    payload = {
+        "learnerName":    learner.get("displayName","?"),
+        "grade":          learner.get("grade","?"),
+        "totalAttempts":  len(l_atts),
+        "recentTrend":    trend,
+        "strongTopics":   strong,
+        "weakTopics":     weak,
+        "recentActivity": recent_activity,
+    }
+
+    ai_prompt = f"""
+You are writing a learning progress report for a parent of a Zimbabwean secondary school student.
+
+Student data (JSON):
+{json.dumps(payload, ensure_ascii=False)[:4000]}
+
+Write a clear, parent-friendly progress report:
+1. OVERALL PROGRESS (plain language, no jargon)
+2. WHAT YOUR CHILD IS DOING WELL
+3. AREAS THAT NEED ATTENTION AT HOME
+4. HOW TO SUPPORT YOUR CHILD (practical, specific suggestions for a parent)
+5. LOOKING AHEAD (encouragement and next milestones)
+
+Tone: warm, accessible, no technical jargon. Address the parent as "your child".
+"""
+    return jsonify({
+        **payload,
+        "aiNarrative":  send_gemini_text(ai_prompt),
+        "generatedAt":  datetime.utcnow().isoformat(),
+    })
+
+
+# =============================================================================
+# 22. REPORTING — ADMIN GLOBAL DASHBOARD
+# =============================================================================
+
+def _compute_global_stats():
+    """
+    Compute platform-wide statistics. Cached as a heavy operation.
+    Called by both the stats endpoint and the AI report endpoint.
+    """
+    attempts  = db_ref.child("attempts").get() or {}
+    users     = db_ref.child("users").get() or {}
+    subjects  = db_ref.child("subjects").get() or {}
+    topics    = db_ref.child("topics").get() or {}
+    classes   = db_ref.child("classes").get() or {}
+    sessions  = db_ref.child("revision_sessions").get() or {}
+    feedback  = db_ref.child("feedback").get() or {}
+
+    all_atts  = [a for a in attempts.values() if a]
+    total_att = len(all_atts)
+    avg_score = round(sum(a.get("percentage",0) for a in all_atts) / total_att, 1) if total_att else 0
+
+    # Role breakdown
+    role_counts = {}
+    for u in users.values():
+        r = u.get("role","unknown")
+        role_counts[r] = role_counts.get(r, 0) + 1
+
+    # Per-learner aggregates for leaderboard
+    learner_agg = {}
+    for a in all_atts:
+        lid = a.get("userId")
+        if not lid: continue
+        if users.get(lid,{}).get("role") != "learner": continue
+        learner_agg.setdefault(lid, {"scoreSum":0,"totalSum":0,"attempts":0})
+        learner_agg[lid]["scoreSum"]  += a.get("score",0)
+        learner_agg[lid]["totalSum"]  += a.get("total",0)
+        learner_agg[lid]["attempts"]  += 1
+
+    top_learners = sorted(
+        [{"uid": lid, "name": users.get(lid,{}).get("displayName","?"),
+          "school": users.get(lid,{}).get("school","?"),
+          "attempts": s["attempts"],
+          "averagePercentage": round((s["scoreSum"]/s["totalSum"])*100,1) if s["totalSum"] else 0}
+         for lid, s in learner_agg.items() if s["attempts"] >= 3],
+        key=lambda x: -x["averagePercentage"]
+    )[:10]
+
+    # Per-teacher: how many students are improving
+    teacher_impact = {}
+    for c in classes.values():
+        tid  = c.get("teacherId")
+        lids = set(c.get("learnerIds") or [])
+        if not tid: continue
+        teacher_impact.setdefault(tid, {"learners":set(),"attempts":0,"scoreSum":0,"totalSum":0})
+        teacher_impact[tid]["learners"].update(lids)
+        for a in all_atts:
+            if a.get("userId") in lids:
+                teacher_impact[tid]["attempts"]  += 1
+                teacher_impact[tid]["scoreSum"]  += a.get("score",0)
+                teacher_impact[tid]["totalSum"]  += a.get("total",0)
+
+    top_teachers = sorted(
+        [{"uid": tid,
+          "name": users.get(tid,{}).get("displayName","?"),
+          "school": users.get(tid,{}).get("school","?"),
+          "totalLearners": len(s["learners"]),
+          "totalAttempts": s["attempts"],
+          "avgLearnerScore": round((s["scoreSum"]/s["totalSum"])*100,1) if s["totalSum"] else 0}
+         for tid, s in teacher_impact.items() if s["attempts"] >= 10],
+        key=lambda x: -x["avgLearnerScore"]
+    )[:10]
+
+    # Subject performance
+    subj_stats, topic_stats = _aggregate_attempts(all_atts)
+    subject_performance = sorted(
+        [{"subjectId": sid, "name": subjects.get(sid,{}).get("name",sid),
+          "attempts": s["attempts"],
+          "averagePercentage": round((s["scoreSum"]/s["totalSum"])*100,1) if s["totalSum"] else 0}
+         for sid, s in subj_stats.items()],
+        key=lambda x: -x["averagePercentage"]
+    )
+
+    # Top struggling topics (most attempted, lowest scores)
+    top_issues = sorted(
+        [{"topicId": t, "name": topics.get(t,{}).get("name",t),
+          "attempts": s["total"],
+          "percentage": round((s["correct"]/s["total"])*100,1)}
+         for t, s in topic_stats.items() if s["total"] >= 10],
+        key=lambda x: (x["percentage"], -x["attempts"])
+    )[:15]
+
+    # Activity timeline — attempts per day for last 30 days
+    from collections import defaultdict
+    daily = defaultdict(int)
+    for a in all_atts:
+        day = a.get("createdAt","")[:10]
+        if day: daily[day] += 1
+    timeline = [{"date": d, "attempts": c}
+                for d, c in sorted(daily.items())[-30:]]
+
+    # Feedback summary
+    feedback_items = list((feedback or {}).values())
+    avg_rating = None
+    if feedback_items:
+        rated = [f.get("rating") for f in feedback_items if f.get("rating")]
+        avg_rating = round(sum(rated)/len(rated),1) if rated else None
+
+    return {
+        "totalUsers":        len(users),
+        "roleCounts":        role_counts,
+        "totalAttempts":     total_att,
+        "platformAvgScore":  avg_score,
+        "totalRevSessions":  len(sessions),
+        "totalFeedback":     len(feedback_items),
+        "avgFeedbackRating": avg_rating,
+        "topLearners":       top_learners,
+        "topTeachers":       top_teachers,
+        "subjectPerformance":subject_performance,
+        "topIssues":         top_issues,
+        "activityTimeline":  timeline,
+    }
+
+
+@app.route("/api/admin/reports/global-stats", methods=["GET"])
+def admin_global_stats():
+    """
+    Raw global statistics — no AI generation, fast.
+    """
+    uid = verify_token(request.headers.get("Authorization"))
+    if not uid: return jsonify({"error": "Unauthorized"}), 401
+    try: require_role(uid, ["admin"])
+    except PermissionError as e: return jsonify({"error": str(e)}), 403
+
+    stats = _compute_global_stats()
+    stats["generatedAt"] = datetime.utcnow().isoformat()
+    return jsonify(stats)
+
+
+@app.route("/api/admin/reports/ai-insight", methods=["POST"])
+def admin_ai_insight():
+    """
+    Generate a deep AI narrative report for stakeholders (investors, AU, UNICEF, etc.).
+    Body: { reportType: "investor" | "curriculum" | "equity" | "progress" | "full" }
+    This is a heavier call — may take 10-20 seconds.
+    """
+    uid = verify_token(request.headers.get("Authorization"))
+    if not uid: return jsonify({"error": "Unauthorized"}), 401
+    try: require_role(uid, ["admin"])
+    except PermissionError as e: return jsonify({"error": str(e)}), 403
+
+    data        = request.get_json() or {}
+    report_type = data.get("reportType", "full")
+
+    stats = _compute_global_stats()
+
+    prompts = {
+        "investor": f"""
+You are a senior analyst preparing an investor briefing for Marka, an AI-powered EdTech platform
+serving secondary school students in Zimbabwe aligned with ZIMSEC and Cambridge curricula.
+
+Platform data (JSON):
+{json.dumps(stats, ensure_ascii=False)[:6000]}
+
+Write a compelling 600-word investor briefing covering:
+1. PLATFORM TRACTION (key metrics, growth signals)
+2. LEARNING OUTCOMES (measurable evidence of student improvement)
+3. TEACHER ADOPTION & IMPACT
+4. CURRICULUM COVERAGE & DEPTH
+5. CHALLENGES BEING ADDRESSED (equity, access, quality)
+6. INVESTMENT OPPORTUNITY (scale potential, monetisation signals)
+
+Tone: confident, data-driven, appropriate for institutional investors and development finance.
+Use specific numbers. Highlight Zimbabwe-specific context.
+""",
+        "curriculum": f"""
+You are a curriculum specialist reviewing learning outcomes data from Marka, an AI EdTech platform
+in Zimbabwe serving Grade 7, O-Level, and A-Level learners.
+
+Platform data (JSON):
+{json.dumps(stats, ensure_ascii=False)[:6000]}
+
+Write a curriculum analysis report:
+1. LEARNING OUTCOMES OVERVIEW (what students are mastering vs struggling with)
+2. SUBJECT-BY-SUBJECT ANALYSIS (strengths and gaps per subject)
+3. CRITICAL KNOWLEDGE GAPS (topics with consistently low scores)
+4. PATTERNS IN LEARNING STALLS (what is blocking progress)
+5. CURRICULUM ALIGNMENT FINDINGS (how well platform content matches exam demands)
+6. RECOMMENDATIONS FOR CURRICULUM DEVELOPERS AND EXAM BOARDS
+
+Tone: academic, evidence-based, suitable for sharing with ZIMSEC, Cambridge, or ministry officials.
+""",
+        "equity": f"""
+You are an education equity researcher reviewing data from Marka, an AI learning platform
+reaching students across Zimbabwe regardless of school quality or location.
+
+Platform data (JSON):
+{json.dumps(stats, ensure_ascii=False)[:6000]}
+
+Write an equity and access impact report for funders such as UNICEF, the AU, or the Gates Foundation:
+1. REACH & INCLUSION (who is using the platform, school diversity)
+2. LEARNING EQUITY SIGNALS (are lower-resourced students improving at scale)
+3. GENDER AND GEOGRAPHIC OBSERVATIONS (where data permits)
+4. BARRIERS TO PROGRESS (what data suggests is still blocking equitable outcomes)
+5. SOCIAL IMPACT MEASUREMENT (how to quantify this for grant reporting)
+6. RECOMMENDATIONS FOR SCALING WITH EQUITY AT CENTRE
+
+Tone: mission-driven, rigorous, suitable for development sector grant reports and impact assessments.
+""",
+        "progress": f"""
+You are an education data scientist synthesising learning progress data from Marka.
+
+Platform data (JSON):
+{json.dumps(stats, ensure_ascii=False)[:6000]}
+
+Write a learning progress synthesis report:
+1. OVERALL PLATFORM LEARNING VELOCITY (how fast are students improving)
+2. TOP PERFORMING COHORTS (what distinguishes them)
+3. STAGNATION PATTERNS (who is not progressing, and possible reasons)
+4. SUBJECT DIFFICULTY LANDSCAPE (which subjects are hardest, which easiest)
+5. AI INTERVENTION EFFECTIVENESS (revision sessions, explanations)
+6. PREDICTIVE OBSERVATIONS (based on current trends, what outcomes can be expected)
+
+Tone: analytical, precise, suitable for academic reporting and programme evaluation.
+""",
+        "full": f"""
+You are the Chief Learning Officer of Marka writing a comprehensive quarterly platform report
+for the founding team, board, and key stakeholders.
+
+Platform data (JSON):
+{json.dumps(stats, ensure_ascii=False)[:6000]}
+
+Write a comprehensive report with these sections:
+1. EXECUTIVE SUMMARY (5 key numbers, 3 key findings)
+2. USER GROWTH & ENGAGEMENT
+3. LEARNING OUTCOMES — WHAT IS WORKING
+4. LEARNING OUTCOMES — WHAT NEEDS ATTENTION
+5. TEACHER EFFECTIVENESS ANALYSIS
+6. TOP CURRICULUM ISSUES AND GAPS
+7. PLATFORM HEALTH (feedback signals, engagement quality)
+8. STRATEGIC OBSERVATIONS (what this data tells us about our product decisions)
+9. RECOMMENDED ACTIONS FOR NEXT QUARTER
+
+Tone: executive-level, data-driven, honest about gaps as well as wins. Suitable for board presentation.
+"""
+    }
+
+    prompt = prompts.get(report_type, prompts["full"])
+    narrative = send_gemini_text(prompt)
+
+    return jsonify({
+        "reportType":  report_type,
+        "stats":       stats,
+        "narrative":   narrative,
+        "generatedAt": datetime.utcnow().isoformat(),
+    })
+
+
+@app.route("/api/admin/reports/subject/<subject_id>", methods=["GET"])
+def admin_subject_deep_dive(subject_id):
+    """
+    Deep dive into one subject — performance, topics, learner cohort, AI analysis.
+    """
+    uid = verify_token(request.headers.get("Authorization"))
+    if not uid: return jsonify({"error": "Unauthorized"}), 401
+    try: require_role(uid, ["admin"])
+    except PermissionError as e: return jsonify({"error": str(e)}), 403
+
+    attempts  = db_ref.child("attempts").get() or {}
+    subj_atts = [a for a in attempts.values() if a.get("subjectId") == subject_id]
+    subjects  = db_ref.child("subjects").get() or {}
+    topics    = db_ref.child("topics").get() or {}
+    users     = db_ref.child("users").get() or {}
+
+    subj_name  = subjects.get(subject_id, {}).get("name", subject_id)
+    _, t_stats = _aggregate_attempts(subj_atts)
+
+    topic_breakdown = sorted(
+        [{"topicId": t, "name": topics.get(t,{}).get("name",t),
+          "attempts": s["total"],
+          "percentage": round((s["correct"]/s["total"])*100,1)}
+         for t, s in t_stats.items() if s["total"] >= 3],
+        key=lambda x: x["percentage"]
+    )
+
+    avg = round(sum(a.get("percentage",0) for a in subj_atts)/len(subj_atts),1) if subj_atts else 0
+
+    payload = {
+        "subjectId": subject_id,
+        "subjectName": subj_name,
+        "totalAttempts": len(subj_atts),
+        "uniqueLearners": len(set(a.get("userId") for a in subj_atts)),
+        "averageScore": avg,
+        "topicBreakdown": topic_breakdown,
+        "hardestTopics": topic_breakdown[:5],
+        "easiestTopics": list(reversed(topic_breakdown))[:5],
+    }
+
+    ai_prompt = f"""
+You are a subject specialist analysing student performance in {subj_name} on the Marka platform.
+
+Performance data (JSON):
+{json.dumps(payload, ensure_ascii=False)[:4000]}
+
+Write a subject performance analysis:
+1. SUBJECT OVERVIEW (participation, average performance)
+2. TOPIC MASTERY MAP (which topics are well understood vs poorly understood)
+3. IDENTIFIED LEARNING BARRIERS (what conceptual gaps underlie the weak topics)
+4. TEACHING RECOMMENDATIONS (for teachers of this subject)
+5. EXAM READINESS ASSESSMENT (based on current performance, are learners ready)
+
+Tone: subject-expert, practical, evidence-based.
+"""
+    return jsonify({**payload, "aiNarrative": send_gemini_text(ai_prompt),
+                   "generatedAt": datetime.utcnow().isoformat()})
+
+
+@app.route("/api/admin/reports/feedback-analysis", methods=["GET"])
+def admin_feedback_analysis():
+    """
+    AI synthesis of all feedback across the platform — themes, issues, sentiment.
+    """
+    uid = verify_token(request.headers.get("Authorization"))
+    if not uid: return jsonify({"error": "Unauthorized"}), 401
+    try: require_role(uid, ["admin"])
+    except PermissionError as e: return jsonify({"error": str(e)}), 403
+
+    feedback   = db_ref.child("feedback").get() or {}
+    fb_list    = [f for f in feedback.values() if f and f.get("message")]
+    if not fb_list:
+        return jsonify({"message": "No feedback submitted yet.", "items": []}), 200
+
+    # Sample up to 100 most recent for AI analysis
+    fb_sample  = sorted(fb_list, key=lambda x: x.get("createdAt",""), reverse=True)[:100]
+    fb_texts   = [{"role": f.get("role","?"), "screen": f.get("screen","?"),
+                   "rating": f.get("rating"), "message": f.get("message","")}
+                  for f in fb_sample]
+
+    # Rating stats
+    rated      = [f.get("rating") for f in fb_list if f.get("rating")]
+    avg_rating = round(sum(rated)/len(rated),1) if rated else None
+    by_screen  = {}
+    for f in fb_list:
+        s = f.get("screen","unknown")
+        by_screen.setdefault(s, 0)
+        by_screen[s] += 1
+
+    ai_prompt = f"""
+You are a UX researcher analysing user feedback for Marka, an EdTech platform.
+
+Feedback sample ({len(fb_texts)} items, JSON):
+{json.dumps(fb_texts, ensure_ascii=False)[:5000]}
+
+Write a structured feedback analysis:
+1. OVERALL SENTIMENT (positive / neutral / negative ratio, key themes)
+2. TOP PRAISED FEATURES (what users love)
+3. TOP PAIN POINTS (what frustrates users, with frequency)
+4. SCREEN-BY-SCREEN ISSUES (any screens generating disproportionate negative feedback)
+5. ROLE-SPECIFIC PATTERNS (do learners, teachers, parents have different issues)
+6. PRIORITISED PRODUCT IMPROVEMENTS (ranked by impact and frequency)
+
+Tone: product team brief. Direct, specific, actionable.
+"""
+    return jsonify({
+        "totalFeedback":    len(fb_list),
+        "avgRating":        avg_rating,
+        "byScreen":         by_screen,
+        "aiNarrative":      send_gemini_text(ai_prompt),
+        "recentFeedback":   fb_sample[:10],
+        "generatedAt":      datetime.utcnow().isoformat(),
+    })
+
 # -----------------------------------------------------------------------------
 # 17. MAIN
 # -----------------------------------------------------------------------------