refactor: separate previous_questions from history_context in quiz generation

Fixes semantic overloading introduced by PR #281 — history_context (conversation
history) is no longer mixed with the generated-questions dedup list.

- Add dedicated `previous_questions` parameter through Generator pipeline
- Extract `_strip_template_knowledge_context()` reused by both generate and repair paths
- Add `_format_previous_questions()` with MAX_PREVIOUS_QUESTIONS=20 cap
- Move language labels into YAML templates (en/zh) to avoid language mixing
- Simplify coordinator to pass raw list instead of string concatenation

Made-with: Cursor

Author: pancacake

deeptutor/agents/question/agents/generator.py

@@ -40,25 +40,30 @@ def __init__(
         self.tool_flags = tool_flags or {}
         self._tool_registry = get_tool_registry()
 
+    MAX_PREVIOUS_QUESTIONS = 20
+
     async def process(
         self,
         template: QuestionTemplate,
         user_topic: str = "",
         preference: str = "",
         history_context: str = "",
+        previous_questions: list[str] | None = None,
     ) -> QAPair:
         """
         Generate one Q-A pair from a template in a single call.
         """
         available_tools = self._build_available_tools_text()
         knowledge_context = str(template.metadata.get("knowledge_context", "")).strip()
+        prev_q_text = self._format_previous_questions(previous_questions)
         payload = await self._generate_payload(
             template=template,
             user_topic=user_topic,
             preference=preference,
             history_context=history_context,
             knowledge_context=knowledge_context,
             available_tools=available_tools,
+            previous_questions=prev_q_text,
         )
         payload, validation = await self._validate_and_repair_payload(
             template=template,
@@ -68,6 +73,7 @@ async def process(
             history_context=history_context,
             knowledge_context=knowledge_context,
             available_tools=available_tools,
+            previous_questions=prev_q_text,
         )
 
         return QAPair(
@@ -112,6 +118,7 @@ async def _generate_payload(
         history_context: str,
         knowledge_context: str,
         available_tools: str,
+        previous_questions: str = "",
     ) -> dict[str, Any]:
         system_prompt = self.get_prompt("system", "")
         user_prompt_template = self.get_prompt("generate", "")
@@ -120,31 +127,21 @@ async def _generate_payload(
                 "Template: {template}\n"
                 "User topic: {user_topic}\n"
                 "Preference: {preference}\n"
-                "Previously generated questions (do not repeat):\n{history_context}\n"
+                "Conversation context: {history_context}\n"
+                "Previously generated questions (do not repeat):\n{previous_questions}\n"
                 "Knowledge context: {knowledge_context}\n"
                 "Enabled tools: {available_tools}\n\n"
                 'Return JSON {{"question_type":"","question":"","options":{{}},"correct_answer":"","explanation":""}}'
             )
 
-        # Serialize the template without the bulky knowledge_context in metadata —
-        # it is already included via the dedicated {knowledge_context} placeholder
-        # and its presence inside the template JSON would cause it to appear twice,
-        # dominating the prompt and making the LLM generate identical questions for
-        # every template regardless of their individual concentrations.
-        template_dict = template.__dict__.copy()
-        if isinstance(template_dict.get("metadata"), dict):
-            stripped_metadata = {
-                k: v
-                for k, v in template_dict["metadata"].items()
-                if k != "knowledge_context"
-            }
-            template_dict["metadata"] = stripped_metadata
+        template_dict = self._strip_template_knowledge_context(template)
 
         user_prompt = user_prompt_template.format(
             template=json.dumps(template_dict, ensure_ascii=False, indent=2),
             user_topic=user_topic,
             preference=preference or "(none)",
             history_context=history_context or "(none)",
+            previous_questions=previous_questions or "(none)",
             knowledge_context=knowledge_context or "(none)",
             available_tools=available_tools,
         )
@@ -191,6 +188,7 @@ async def _validate_and_repair_payload(
         history_context: str,
         knowledge_context: str,
         available_tools: str,
+        previous_questions: str = "",
     ) -> tuple[dict[str, Any], dict[str, Any]]:
         expected_type = self._normalize_question_type(template.question_type)
         normalized = self._normalize_payload_shape(expected_type, payload)
@@ -207,6 +205,7 @@ async def _validate_and_repair_payload(
                 history_context=history_context,
                 knowledge_context=knowledge_context,
                 available_tools=available_tools,
+                previous_questions=previous_questions,
             )
             if repaired_payload:
                 candidate = self._normalize_payload_shape(expected_type, repaired_payload)
@@ -234,14 +233,17 @@ async def _repair_payload(
         history_context: str,
         knowledge_context: str,
         available_tools: str,
+        previous_questions: str = "",
     ) -> dict[str, Any]:
         expected_type = self._normalize_question_type(template.question_type)
+        template_dict = self._strip_template_knowledge_context(template)
         repair_prompt = (
             "You are repairing an invalid quiz question JSON.\n\n"
-            f"QuestionTemplate:\n{json.dumps(template.__dict__, ensure_ascii=False, indent=2)}\n\n"
+            f"QuestionTemplate:\n{json.dumps(template_dict, ensure_ascii=False, indent=2)}\n\n"
             f"User topic:\n{user_topic or '(none)'}\n\n"
             f"User preference:\n{preference or '(none)'}\n\n"
             f"Conversation context:\n{history_context or '(none)'}\n\n"
+            f"Previously generated questions:\n{previous_questions or '(none)'}\n\n"
             f"Knowledge context:\n{knowledge_context or '(none)'}\n\n"
             f"Enabled tools:\n{available_tools}\n\n"
             f"Invalid payload:\n{json.dumps(payload, ensure_ascii=False, indent=2)}\n\n"
@@ -397,6 +399,25 @@ def _enabled_tool_names(self) -> list[str]:
             enabled_tools.append("code_execution")
         return enabled_tools
 
+    @staticmethod
+    def _strip_template_knowledge_context(template: QuestionTemplate) -> dict[str, Any]:
+        """Strip knowledge_context from template metadata to avoid prompt duplication."""
+        template_dict = template.__dict__.copy()
+        if isinstance(template_dict.get("metadata"), dict):
+            template_dict["metadata"] = {
+                k: v
+                for k, v in template_dict["metadata"].items()
+                if k != "knowledge_context"
+            }
+        return template_dict
+
+    @classmethod
+    def _format_previous_questions(cls, questions: list[str] | None) -> str:
+        if not questions:
+            return ""
+        capped = questions[-cls.MAX_PREVIOUS_QUESTIONS :]
+        return "\n".join(f"{i}. {q}" for i, q in enumerate(capped, 1))
+
     @staticmethod
     def _parse_json_like(content: str) -> dict[str, Any]:
         if not content or not content.strip():

deeptutor/agents/question/coordinator.py

@@ -286,25 +286,14 @@ async def _generation_loop(
                 },
             )
 
-            # Build cumulative context from questions already generated in this
-            # session so the Generator can avoid producing duplicates.
-            cumulative_history = history_context
-            if generated_questions:
-                previous = "\n".join(
-                    f"Q{i}: {q}" for i, q in enumerate(generated_questions, start=1)
-                )
-                if cumulative_history:
-                    cumulative_history = f"{cumulative_history}\n\nQuestions generated in this session:\n{previous}"
-                else:
-                    cumulative_history = f"Questions generated in this session:\n{previous}"
-
             success = True
             try:
                 qa_pair = await generator.process(
                     template=template,
                     user_topic=user_topic,
                     preference=preference,
-                    history_context=cumulative_history,
+                    history_context=history_context,
+                    previous_questions=generated_questions or None,
                 )
             except Exception as exc:
                 success = False

deeptutor/agents/question/prompts/en/generator.yaml

@@ -19,9 +19,12 @@ generate: |
   Tools enabled by the user:
   {available_tools}
 
-  Previously generated questions in this session (your new question MUST be different from all of these):
+  Conversation context:
   {history_context}
 
+  Previously generated questions in this session (your new question MUST be different from all of these):
+  {previous_questions}
+
   Requirements:
   - Keep strict alignment with template.concentration and template.difficulty.
   - Respect template.question_type exactly. Do not silently change it.

deeptutor/agents/question/prompts/zh/generator.yaml

@@ -19,9 +19,12 @@ generate: |
   用户当前启用的工具：
   {available_tools}
 
-  本次会话中已生成的题目（你的新题目必须与以下所有题目不同）：
+  对话上下文：
   {history_context}
 
+  本次会话中已生成的题目（你的新题目必须与以下所有题目不同）：
+  {previous_questions}
+
   要求：
   - 严格对齐 template.concentration 与 template.difficulty。
   - 必须严格遵循 template.question_type，不要私自改题型。