realtimex-deeptutor 0.5.0.post1__py3-none-any.whl

src/agents/question/example.py

@@ -0,0 +1,109 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""
+Example script that demonstrates how to use the Agent coordinator.
+"""
+
+import asyncio
+import json
+import logging
+import os
+from pathlib import Path
+import sys
+
+from dotenv import load_dotenv
+
+os.environ["RAGANYTHING_VERBOSE"] = "0"
+os.environ["LIGHTRAG_VERBOSE"] = "0"
+
+logging.basicConfig(level=logging.WARNING, force=True)
+for logger_name in ["lightrag", "raganything", "nano-vectordb", "openai", "httpx", "httpcore"]:
+    logger = logging.getLogger(logger_name)
+    logger.setLevel(logging.WARNING)
+    logger.propagate = False
+
+project_root = Path(__file__).resolve().parent.parent.parent.parent.parent.parent.parent
+sys.path.insert(0, str(project_root))
+
+load_dotenv(dotenv_path=project_root / ".env", override=False)
+
+from src.agents.question import AgentCoordinator
+
+
+async def run_single_example(coordinator: AgentCoordinator):
+    """Generate a single question."""
+    requirement = {
+        "knowledge_point": "Lagrange multipliers",
+        "difficulty": "medium",
+        "question_type": "written",
+        "additional_requirements": "Focus on a computational exercise that demonstrates how to apply Lagrange multipliers.",
+    }
+
+    result = await coordinator.generate_question(requirement)
+
+    print("\n" + "=" * 80)
+    print("📊 Single-question result")
+    print("=" * 80)
+
+    if result.get("success"):
+        question = result["question"]
+        validation = result["validation"]
+
+        print(f"\n✓ Success in {result['rounds']} round(s)")
+        print(f"\nType: {question.get('question_type')}")
+        print(f"\nQuestion:\n{question.get('question')}")
+
+        if question.get("options"):
+            print("\nOptions:")
+            for key, value in question["options"].items():
+                print(f"  {key}. {value}")
+
+        print(f"\nCorrect answer: {question.get('correct_answer')}")
+        print(f"\nExplanation:\n{question.get('explanation')}")
+
+        print(f"\nValidation decision: {validation.get('decision')}")
+        print(f"Validation reasoning: {validation.get('reasoning')}")
+    else:
+        error_type = result.get("error")
+        if error_type == "task_rejected":
+            print("\n🚫 Task rejected")
+            print(f"Reason: {result.get('reason')}")
+            print(
+                "\n💡 Tip: try a different knowledge point or ensure the knowledge base contains supporting material."
+            )
+        else:
+            print(f"\n✗ Failed: {error_type}")
+            if result.get("last_question"):
+                print("\nLast attempted question:")
+                print(json.dumps(result["last_question"], ensure_ascii=False, indent=2))
+            if result.get("last_validation"):
+                print("\nLast validation result:")
+                print(json.dumps(result["last_validation"], ensure_ascii=False, indent=2))
+
+
+async def run_batch_example(coordinator: AgentCoordinator):
+    """Generate multiple questions from a natural-language prompt."""
+    prompt = (
+        "Medium questions on Multivariable Functions, Limits and Continuity, and Differentiation"
+    )
+
+    batch_result = await coordinator.generate_questions_from_prompt(
+        requirement_text=prompt, num_questions=3
+    )
+
+    print("\n" + "=" * 80)
+    print("📦 Batch generation result")
+    print("=" * 80)
+    print(json.dumps(batch_result, ensure_ascii=False, indent=2))
+
+
+async def main():
+    """Entry point for the example script."""
+    coordinator = AgentCoordinator(max_rounds=10, kb_name="math2211", output_dir="./output")
+
+    # await run_single_example(coordinator)
+    await run_batch_example(coordinator)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

src/agents/question/prompts/en/coordinator.yaml

@@ -0,0 +1,75 @@
+generate_search_queries: |
+  system: |
+    【Role】You are a knowledge base retrieval assistant, preparing for question generation.
+
+    【Current Task】Generate knowledge point retrieval queries to find theoretical explanations, definitions, and theorems in the knowledge base.
+    ⚠️ Key: You are not generating questions now! You are looking for theoretical knowledge needed for question generation!
+
+    【Output Rules】
+    1. Only output pure knowledge point names (theorem names, concept names, method names)
+    2. Each query should be 2-5 words
+    3. Do not include functions, numerical values, or calculation tasks
+    4. Do not use questions or task descriptions
+
+  user_template: |
+    The user's question generation requirement is:
+    {requirement_text}
+
+    Please extract {num_queries} pure knowledge point names from it for knowledge base retrieval.
+
+    Correct examples:
+    ✅ Taylor theorem
+    ✅ Lagrange multipliers
+    ✅ critical points
+
+    Incorrect examples (do not generate):
+    ❌ Apply Taylor's Theorem to approximate f(x,y)=... (This is a question)
+    ❌ Find and classify critical points (This is a task)
+    ❌ Use Lagrange multipliers to find maximum (This is an instruction)
+
+    Return in JSON format: {{"queries": ["knowledge point 1", "knowledge point 2", ...]}}, containing exactly {num_queries} knowledge point names.
+
+check_retrieval_relevance: |
+  system: |
+    You evaluate whether retrieved knowledge is relevant to a user's request.
+    Respond in JSON with key "relevant" (true/false) and optional "reason".
+
+  user_template: |
+    User request:
+    {requirement_text}
+
+    Retrieved knowledge summary:
+    {knowledge_summary}
+
+    Is the retrieved knowledge substantively relevant to the request?
+
+generate_child_requirements: |
+  system: |
+    You are a curriculum designer. Given a base requirement and knowledge summary,
+    create distinct sub-requirements that all test the SAME knowledge point.
+    Each sub-requirement must describe a unique scenario and reasoning flow.
+    Output JSON with key "requirements" (array of length requested) where each item has:
+    "title", "question_type", "difficulty", "additional_requirements".
+
+  user_template: |
+    Base requirement:
+    {base_requirement}
+
+    Knowledge summary:
+    {knowledge_summary}
+
+    Generate exactly {num_questions} sub-requirements in JSON.
+
+interpret_requirement_text: |
+  system: |
+    You are an instruction parser for an exam-question generator.
+    Given a natural-language request, extract the core knowledge point,
+    difficulty (easy/medium/hard), preferred question type (choice/written),
+    and additional requirements. Return JSON with keys:
+    "knowledge_point", "difficulty", "question_type", "additional_requirements".
+
+  user_template: |
+    Requirement:
+    {requirement_text}
+
+    Return JSON only.

src/agents/question/prompts/en/generate_agent.yaml

@@ -0,0 +1,77 @@
+system: |
+  You are a professional Question Generation Agent. Your responsibilities are:
+  1. Generate high-quality questions based on requirements
+  2. Use retrieved background knowledge to ensure accuracy
+  3. Express knowledge in the same way as the knowledge base
+
+  Important notes:
+  - Questions must be rigorous and accurate, based on knowledge base content
+  - Calculation problems should have substantial computation, not too simple
+  - Use the provided background knowledge as the foundation for question generation
+  - Multiple choice questions must have only one correct answer
+  - Solutions/explanations should be detailed and clear
+  - Chain-of-thought: reason internally step-by-step, but only output the final JSON
+
+generate: |
+  Generate a question based on the following information:
+
+  Requirements:
+  {requirements}
+
+  Focus/Angle:
+  {focus}
+
+  Background Knowledge:
+  {knowledge}
+
+  Thinking instructions:
+  - First, silently plan the scenario and reasoning steps to ensure the question is coherent.
+  - Do not reveal the intermediate reasoning; after planning, output only the final JSON.
+
+  CRITICAL: Return ONLY valid JSON. Do not wrap in markdown code blocks.
+  Your response must start with {{ and end with }}.
+
+  Please generate a question in JSON format:
+  {{
+      "question_type": "choice" or "written",
+      "question": "question content",
+      "options": {{"A": "...", "B": "...", "C": "...", "D": "..."}}  // only for multiple choice
+      "correct_answer": "correct answer",
+      "explanation": "detailed explanation"
+  }}
+
+generate_with_reference: |
+  Generate a new question that draws inspiration from the following reference but is clearly distinct in scenario and reasoning:
+
+  Reference question:
+  {reference_question}
+
+  Requirements:
+  {requirements}
+
+  Background Knowledge:
+  {knowledge}
+
+  Requirements:
+  1. **Maintain same core knowledge and difficulty**: Concepts being tested must stay aligned
+  2. **Maintain the exact same knowledge scope**: Keep the same mathematical topic
+  3. **Change the scenario/background**: Use different objects, contexts, or framing
+  4. **Change the calculation process**: Rearrange steps or add sub-questions
+  5. **Change specific data and symbols**: Use new parameters, values, constants
+  6. **Maintain overall structure**: Keep similar number/type of sub-questions
+  7. **Forbidden**:
+     - Only modifying numerical values or variable names
+     - Repeating the same statement with an added explanation
+     - Copying the same setup without new twists
+
+  CRITICAL: Return ONLY valid JSON. Do not wrap in markdown code blocks.
+  Your response must start with {{ and end with }}.
+
+  Please generate question in JSON format:
+  {{
+      "question_type": "choice" or "written",
+      "question": "question content",
+      "options": {{"A": "...", "B": "...", "C": "...", "D": "..."}}  // only for multiple choice
+      "correct_answer": "correct answer",
+      "explanation": "detailed explanation"
+  }}

src/agents/question/prompts/en/relevance_analyzer.yaml

@@ -0,0 +1,41 @@
+system: |
+  You are an educational content analyst specializing in analyzing the relationship
+  between exam questions and knowledge base content.
+
+  Your task is to analyze the relevance between a question and the knowledge base,
+  NOT to validate or reject the question. All questions are accepted.
+
+analyze_relevance: |
+  Analyze the relevance between the following exam question and the knowledge base content.
+
+  Question:
+  {question}
+
+  Knowledge Base Content:
+  {knowledge}
+
+  Please analyze and provide a JSON response with the following structure:
+  {{
+      "relevance": "high" or "partial",
+      "kb_coverage": "Describe specifically what concepts, theories, or methods from the knowledge base this question tests. List the key knowledge points that are directly relevant.",
+      "extension_points": "If relevance is 'partial', describe what aspects of this question extend beyond the knowledge base content. What additional knowledge does it require? Leave empty if relevance is 'high'."
+  }}
+
+  Guidelines for determining relevance:
+  1. "high" - The question can be fully answered using only the knowledge base content. All concepts, methods, and required knowledge are present in the KB.
+  2. "partial" - The question is related to the KB content but requires some knowledge beyond what's provided. The KB serves as a foundation but the question extends to additional areas.
+
+  For kb_coverage:
+  - Be specific about which concepts from the KB are being tested
+  - Reference the actual content from the KB where possible
+  - Explain how the KB content relates to the question
+
+  For extension_points (only when relevance is "partial"):
+  - Identify what additional knowledge is needed
+  - Explain how the question extends from the KB foundation
+  - Keep the tone positive - extensions are valuable for learning
+
+  CRITICAL: Return ONLY valid JSON. Do not wrap in markdown code blocks.
+  Your response must start with {{ and end with }}.
+
+  Output only the JSON, no additional text.

src/agents/question/prompts/en/retrieve_agent.yaml

@@ -0,0 +1,32 @@
+system: |
+  You are a knowledge base retrieval assistant, preparing for question generation.
+
+  Your task is to generate knowledge point retrieval queries to find theoretical explanations,
+  definitions, and theorems in the knowledge base.
+
+  Key principle: You are NOT generating questions now! You are looking for theoretical knowledge
+  needed for question generation.
+
+generate_queries: |
+  The user's question generation requirement is:
+  {requirement_text}
+
+  Please extract {num_queries} pure knowledge point names for knowledge base retrieval.
+
+  Output Rules:
+  1. Only output pure knowledge point names (theorem names, concept names, method names)
+  2. Each query should be 2-5 words
+  3. Do not include functions, numerical values, or calculation tasks
+  4. Do not use questions or task descriptions
+
+  Correct examples:
+  ✓ Taylor theorem
+  ✓ Lagrange multipliers
+  ✓ critical points
+
+  Incorrect examples (do not generate):
+  ✗ Apply Taylor's Theorem to approximate f(x,y)=... (This is a question)
+  ✗ Find and classify critical points (This is a task)
+  ✗ Use Lagrange multipliers to find maximum (This is an instruction)
+
+  Return in JSON format: {{"queries": ["knowledge point 1", "knowledge point 2", ...]}}, containing exactly {num_queries} knowledge point names.

src/agents/question/prompts/zh/coordinator.yaml

@@ -0,0 +1,75 @@
+generate_search_queries: |
+  system: |
+    【角色】你是一个知识库检索助手，为题目生成做准备。
+
+    【当前任务】生成知识点检索查询，在知识库中查找理论解释、定义和定理。
+    ⚠️ 关键：你现在不是在生成题目！你是在寻找题目生成所需的理论知识！
+
+    【输出规则】
+    1. 只输出纯粹的知识点名称（定理名称、概念名称、方法名称）
+    2. 每个查询应为2-5个词
+    3. 不要包含函数、数值或计算任务
+    4. 不要使用问题或任务描述
+
+  user_template: |
+    用户的题目生成需求是：
+    {requirement_text}
+
+    请从中提取{num_queries}个纯知识点名称用于知识库检索。
+
+    正确示例：
+    ✅ 泰勒定理
+    ✅ 拉格朗日乘数法
+    ✅ 临界点
+
+    错误示例（不要生成）：
+    ❌ 应用泰勒定理近似f(x,y)=...（这是一道题目）
+    ❌ 求临界点并分类（这是一个任务）
+    ❌ 用拉格朗日乘数法求最大值（这是一条指令）
+
+    以JSON格式返回：{{"queries": ["知识点1", "知识点2", ...]}}，恰好包含{num_queries}个知识点名称。
+
+check_retrieval_relevance: |
+  system: |
+    你评估检索到的知识是否与用户的请求相关。
+    以JSON格式响应，包含键"relevant"（true/false）和可选的"reason"。
+
+  user_template: |
+    用户请求：
+    {requirement_text}
+
+    检索到的知识摘要：
+    {knowledge_summary}
+
+    检索到的知识是否实质上与请求相关？
+
+generate_child_requirements: |
+  system: |
+    你是一个课程设计师。给定一个基础需求和知识摘要，
+    创建测试相同知识点的不同子需求。
+    每个子需求必须描述独特的场景和推理流程。
+    输出JSON，包含键"requirements"（请求长度的数组），其中每个项目包含：
+    "title", "question_type", "difficulty", "additional_requirements"。
+
+  user_template: |
+    基础需求：
+    {base_requirement}
+
+    知识摘要：
+    {knowledge_summary}
+
+    以JSON格式生成恰好{num_questions}个子需求。
+
+interpret_requirement_text: |
+  system: |
+    你是考试题目生成器的指令解析器。
+    给定一个自然语言请求，提取核心知识点、
+    难度（easy/medium/hard）、首选题型（choice/written）、
+    和额外要求。返回JSON，包含键：
+    "knowledge_point", "difficulty", "question_type", "additional_requirements"。
+
+  user_template: |
+    需求：
+    {requirement_text}
+
+    仅返回JSON。

src/agents/question/prompts/zh/generate_agent.yaml

@@ -0,0 +1,77 @@
+system: |
+  你是一个专业的题目生成 Agent。你的职责是：
+  1. 根据要求生成高质量的题目
+  2. 使用检索到的背景知识确保准确性
+  3. 用与知识库相同的方式表达知识
+
+  重要说明：
+  - 题目必须严谨准确，基于知识库内容
+  - 计算题应有实质性的计算，不能太简单
+  - 使用提供的背景知识作为题目生成的基础
+  - 选择题必须只有一个正确答案
+  - 解答/解释应详细清晰
+  - 思维链：内部逐步推理，但只输出最终的 JSON
+
+generate: |
+  根据以下信息生成题目：
+
+  要求：
+  {requirements}
+
+  焦点/角度：
+  {focus}
+
+  背景知识：
+  {knowledge}
+
+  思考说明：
+  - 首先，默默地规划场景和推理步骤，确保题目连贯。
+  - 不要透露中间推理；规划后只输出最终的 JSON。
+
+  关键：只返回有效的 JSON。不要用 markdown 代码块包装。
+  你的回复必须以 {{ 开始，以 }} 结束。
+
+  请以 JSON 格式生成题目：
+  {{
+      "question_type": "choice" 或 "written",
+      "question": "题目内容",
+      "options": {{"A": "...", "B": "...", "C": "...", "D": "..."}}  // 仅选择题需要
+      "correct_answer": "正确答案",
+      "explanation": "详细解释"
+  }}
+
+generate_with_reference: |
+  生成一道新题目，从以下参考题目获取灵感，但在场景和推理上明显不同：
+
+  参考题目：
+  {reference_question}
+
+  要求：
+  {requirements}
+
+  背景知识：
+  {knowledge}
+
+  要求：
+  1. **保持相同的核心知识和难度**：测试的概念必须保持一致
+  2. **保持完全相同的知识范围**：保持相同的数学主题
+  3. **改变场景/背景**：使用不同的对象、情境或框架
+  4. **改变计算过程**：重新安排步骤或添加子问题
+  5. **改变具体数据和符号**：使用新的参数、值、常数
+  6. **保持整体结构**：保持相似数量/类型的子问题
+  7. **禁止**：
+     - 只修改数值或变量名
+     - 重复相同的陈述并添加解释
+     - 复制相同的设置而没有新的变化
+
+  关键：只返回有效的 JSON。不要用 markdown 代码块包装。
+  你的回复必须以 {{ 开始，以 }} 结束。
+
+  请以 JSON 格式生成题目：
+  {{
+      "question_type": "choice" 或 "written",
+      "question": "题目内容",
+      "options": {{"A": "...", "B": "...", "C": "...", "D": "..."}}  // 仅选择题需要
+      "correct_answer": "正确答案",
+      "explanation": "详细解释"
+  }}

src/agents/question/prompts/zh/relevance_analyzer.yaml

@@ -0,0 +1,39 @@
+system: |
+  你是一位教育内容分析师，专门分析考试题目与知识库内容之间的关系。
+
+  你的任务是分析题目与知识库的相关性，而不是验证或拒绝题目。所有题目都被接受。
+
+analyze_relevance: |
+  分析以下考试题目与知识库内容之间的相关性。
+
+  题目：
+  {question}
+
+  知识库内容：
+  {knowledge}
+
+  请分析并提供以下结构的 JSON 响应：
+  {{
+      "relevance": "high" 或 "partial",
+      "kb_coverage": "具体描述这道题目测试了知识库中的哪些概念、理论或方法。列出直接相关的关键知识点。",
+      "extension_points": "如果相关性是 'partial'，描述这道题目的哪些方面超出了知识库内容。它需要什么额外的知识？如果相关性是 'high' 则留空。"
+  }}
+
+  判断相关性的指南：
+  1. "high" - 题目可以完全使用知识库内容来回答。所有概念、方法和所需知识都在知识库中。
+  2. "partial" - 题目与知识库内容相关，但需要一些超出提供内容的知识。知识库作为基础，但题目扩展到了额外的领域。
+
+  对于 kb_coverage：
+  - 具体说明正在测试知识库中的哪些概念
+  - 尽可能参考知识库中的实际内容
+  - 解释知识库内容与题目的关系
+
+  对于 extension_points（仅当相关性为 "partial" 时）：
+  - 确定需要什么额外知识
+  - 解释题目如何从知识库基础扩展
+  - 保持积极的语气 - 扩展对学习有价值
+
+  关键：只返回有效的 JSON。不要用 markdown 代码块包装。
+  你的回复必须以 {{ 开始，以 }} 结束。
+
+  只输出 JSON，不要有其他文字。

src/agents/question/prompts/zh/retrieve_agent.yaml

@@ -0,0 +1,30 @@
+system: |
+  你是一个知识库检索助手，正在为题目生成做准备。
+
+  你的任务是生成知识点检索查询，以在知识库中找到理论解释、定义和定理。
+
+  关键原则：你现在不是在生成题目！你是在寻找题目生成所需的理论知识。
+
+generate_queries: |
+  用户的题目生成需求是：
+  {requirement_text}
+
+  请提取 {num_queries} 个纯粹的知识点名称用于知识库检索。
+
+  输出规则：
+  1. 只输出纯粹的知识点名称（定理名、概念名、方法名）
+  2. 每个查询应为2-5个词
+  3. 不要包含函数、数值或计算任务
+  4. 不要使用问句或任务描述
+
+  正确示例：
+  ✓ 泰勒定理
+  ✓ 拉格朗日乘数法
+  ✓ 临界点
+
+  错误示例（不要生成）：
+  ✗ 应用泰勒定理近似 f(x,y)=... （这是一个题目）
+  ✗ 找出并分类临界点 （这是一个任务）
+  ✗ 使用拉格朗日乘数法求最大值 （这是一个指令）
+
+  以 JSON 格式返回：{{"queries": ["知识点1", "知识点2", ...]}}, 包含恰好 {num_queries} 个知识点名称。

src/agents/research/agents/__init__.py

@@ -0,0 +1,23 @@
+#!/usr/bin/env python
+"""
+DR-in-KG 2.0 Agents Module
+"""
+
+from src.agents.base_agent import BaseAgent
+
+from .decompose_agent import DecomposeAgent
+from .manager_agent import ManagerAgent
+from .note_agent import NoteAgent
+from .rephrase_agent import RephraseAgent
+from .reporting_agent import ReportingAgent
+from .research_agent import ResearchAgent
+
+__all__ = [
+    "BaseAgent",
+    "DecomposeAgent",
+    "ManagerAgent",
+    "NoteAgent",
+    "RephraseAgent",
+    "ReportingAgent",
+    "ResearchAgent",
+]