Fix: Add prompt size check and auto-truncate students to prevent empty LLM responses

When exam data is too large for the model's context window, the report
generator now automatically truncates student data (50% → 25%) instead
of failing. Also switches to compact JSON serialization to save ~20-30%
tokens, and dynamically adjusts max_completion_tokens based on available
space.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

chatkit/backend/app/report_generator.py

@@ -3,12 +3,54 @@
 from __future__ import annotations
 
 import json
+import logging
 import re
 
 from openai import AsyncOpenAI
 
 from .config import get_settings
 
+logger = logging.getLogger(__name__)
+
+# Context window sizes per model (tokens)
+MODEL_CONTEXT_LIMITS: dict[str, int] = {
+    "gpt-5.4": 128_000,
+    "gpt-5.4-pro": 128_000,
+    "gpt-5.3-chat-latest": 128_000,
+    "gpt-5-mini": 128_000,
+    "gpt-4o": 128_000,
+    "gpt-4o-mini": 128_000,
+}
+
+DEFAULT_CONTEXT_LIMIT = 128_000
+# Minimum tokens we need for a useful HTML report
+MIN_COMPLETION_TOKENS = 2_000
+DESIRED_COMPLETION_TOKENS = 16_384
+TOKEN_SAFETY_MARGIN = 256
+
+
+def _estimate_tokens(text: str) -> int:
+    """Estimate token count using char-count heuristic.
+
+    CJK text averages ~1.5-2 tokens/char; English ~4 chars/token.
+    Using len//3 is a conservative middle-ground that slightly overestimates,
+    which is the safe direction for a pre-flight check.
+    """
+    return max(1, len(text) // 3)
+
+
+def _truncate_students(student_answers: dict, max_students: int) -> tuple[dict, int, int]:
+    """Truncate student list to fit within token budget.
+
+    Returns (truncated_data, original_count, kept_count).
+    """
+    students = student_answers.get("students", [])
+    original_count = len(students)
+    if original_count <= max_students:
+        return student_answers, original_count, original_count
+    truncated = {**student_answers, "students": students[:max_students]}
+    return truncated, original_count, max_students
+
 
 REPORT_SYSTEM_PROMPT = """You are ClassLens, an AI teaching assistant that creates beautiful, comprehensive exam analysis reports.
 
@@ -96,9 +138,9 @@ def get_default_prompt() -> str:
 def fill_prompt(template: str, questions: dict, student_answers: dict, teacher_answers: dict) -> str:
     """Fill the prompt template with actual data."""
     return template.format(
-        questions=json.dumps(questions, ensure_ascii=False, indent=2),
-        student_answers=json.dumps(student_answers, ensure_ascii=False, indent=2),
-        teacher_answers=json.dumps(teacher_answers, ensure_ascii=False, indent=2),
+        questions=json.dumps(questions, ensure_ascii=False, separators=(",", ":")),
+        student_answers=json.dumps(student_answers, ensure_ascii=False, separators=(",", ":")),
+        teacher_answers=json.dumps(teacher_answers, ensure_ascii=False, separators=(",", ":")),
     )
 
 
@@ -129,8 +171,52 @@ async def generate_report(
     """
     settings = get_settings()
     client = AsyncOpenAI(api_key=settings.openai_api_key)
-
-    filled_prompt = fill_prompt(prompt_template, questions_data, student_answers_data, teacher_answers_data)
+    context_limit = MODEL_CONTEXT_LIMITS.get(model, DEFAULT_CONTEXT_LIMIT)
+
+    # --- Try full data first, auto-truncate students if too large ---
+    current_student_data = student_answers_data
+    total_students = len(student_answers_data.get("students", []))
+    truncated = False
+
+    for attempt in range(3):  # full → 50% → 25% of students
+        filled_prompt = fill_prompt(prompt_template, questions_data, current_student_data, teacher_answers_data)
+        prompt_tokens = _estimate_tokens(REPORT_SYSTEM_PROMPT) + _estimate_tokens(filled_prompt)
+        available_for_completion = context_limit - prompt_tokens - TOKEN_SAFETY_MARGIN
+
+        logger.info(
+            "Attempt %d — prompt ~%d tokens, available for completion: %d (model: %s, students: %d)",
+            attempt + 1, prompt_tokens, available_for_completion, model,
+            len(current_student_data.get("students", [])),
+        )
+
+        if available_for_completion >= MIN_COMPLETION_TOKENS:
+            break
+
+        # Reduce student count: 50% → 25% of original
+        fraction = 0.5 if attempt == 0 else 0.25
+        max_students = max(1, int(total_students * fraction))
+        current_student_data, _, kept = _truncate_students(student_answers_data, max_students)
+        truncated = True
+        logger.warning(
+            "Prompt too large, truncating students: %d → %d", total_students, kept,
+        )
+    else:
+        # Still too large after all truncation attempts
+        raise ValueError(
+            f"提示內容過大（約 {prompt_tokens:,} tokens），即使只保留 25% 的學生資料仍超出模型限制。"
+            f"請減少題目數量或簡化提示。"
+        )
+
+    max_completion = min(DESIRED_COMPLETION_TOKENS, available_for_completion)
+
+    # Add a note to the prompt if data was truncated
+    if truncated:
+        kept_count = len(current_student_data.get("students", []))
+        truncation_note = (
+            f"\n\n⚠️ 注意：因資料量過大，僅包含 {kept_count}/{total_students} 位學生的答案。"
+            f"請在報告中註明此為部分學生的抽樣分析。"
+        )
+        filled_prompt += truncation_note
 
     kwargs: dict = {
         "model": model,
@@ -138,7 +224,7 @@ async def generate_report(
             {"role": "system", "content": REPORT_SYSTEM_PROMPT},
             {"role": "user", "content": filled_prompt},
         ],
-        "max_completion_tokens": 16384,
+        "max_completion_tokens": max_completion,
         "temperature": 0.3,
     }
 
@@ -148,7 +234,7 @@ async def generate_report(
         # Some models may not support max_completion_tokens; fallback
         if "max_completion_tokens" in str(e):
             kwargs.pop("max_completion_tokens")
-            kwargs["max_tokens"] = 16384
+            kwargs["max_tokens"] = max_completion
             response = await client.chat.completions.create(**kwargs)
         else:
             raise