deeptutor-questions 1.7.0__py3-none-any.whl

deeptutor/agents/question/__init__.py

@@ -0,0 +1,33 @@
+"""Question generation package.
+
+The main entry point is :class:`~deeptutor.agents.question.pipeline.QuestionPipeline`.
+Lightweight names (``FollowupAgent``, ``QuizTemplate``, ``QuizPair``, etc.)
+are resolved lazily so callers that only need one symbol don't eagerly
+import the full pipeline + its LLM dependencies.
+"""
+
+from importlib import import_module
+from typing import Any
+
+__all__ = [
+    "AgentCoordinator",
+    "FollowupAgent",
+    "QuestionPipeline",
+    "QuizTemplate",
+    "QuizPair",
+    "QuizPlan",
+    "QuizHistoryEntry",
+]
+
+
+def __getattr__(name: str) -> Any:
+    if name == "AgentCoordinator":
+        module = import_module("deeptutor.agents.question.coordinator")
+        return getattr(module, name)
+    if name == "FollowupAgent":
+        module = import_module("deeptutor.agents.question.agents.followup_agent")
+        return getattr(module, name)
+    if name in {"QuestionPipeline", "QuizTemplate", "QuizPair", "QuizPlan", "QuizHistoryEntry"}:
+        module = import_module("deeptutor.agents.question.pipeline")
+        return getattr(module, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

deeptutor/agents/question/agents/__init__.py

@@ -0,0 +1,19 @@
+"""Question generation sub-agents.
+
+Currently only the standalone single-call ``FollowupAgent`` lives here —
+the per-question / per-batch agents (idea_agent, generator) were
+replaced by the single :mod:`deeptutor.agents.question.pipeline` module
+during the Phase A → C refactor.
+"""
+
+from importlib import import_module
+from typing import Any
+
+__all__ = ["FollowupAgent"]
+
+
+def __getattr__(name: str) -> Any:
+    if name == "FollowupAgent":
+        module = import_module("deeptutor.agents.question.agents.followup_agent")
+        return getattr(module, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

deeptutor/agents/question/agents/followup_agent.py

@@ -0,0 +1,118 @@
+#!/usr/bin/env python
+"""
+Single-call follow-up agent for quiz question threads.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from deeptutor.agents.base_agent import BaseAgent
+from deeptutor.core.trace import build_trace_metadata, new_call_id
+from deeptutor.services.prompt.language import append_language_directive
+
+
+class FollowupAgent(BaseAgent):
+    """Answer follow-up questions about a single quiz item in one LLM call."""
+
+    def __init__(self, language: str = "en", **kwargs: Any) -> None:
+        super().__init__(
+            module_name="question",
+            agent_name="followup_agent",
+            language=language,
+            **kwargs,
+        )
+
+    async def process(
+        self,
+        *,
+        user_message: str,
+        question_context: dict[str, Any],
+        history_context: str = "",
+        attachments: list[Any] | None = None,
+    ) -> str:
+        system_prompt = append_language_directive(
+            self.get_prompt("system", ""),
+            self.language,
+        )
+        user_prompt_template = self.get_prompt("answer_followup", "")
+        if not user_prompt_template:
+            user_prompt_template = (
+                "Question context:\n{question_context}\n\n"
+                "Conversation history:\n{history_context}\n\n"
+                "User follow-up:\n{user_message}\n"
+            )
+
+        user_prompt = user_prompt_template.format(
+            question_context=self._render_question_context(question_context),
+            history_context=history_context or "(none)",
+            user_message=user_message.strip() or "(empty)",
+        )
+
+        _chunks: list[str] = []
+        async for _c in self.stream_llm(
+            user_prompt=user_prompt,
+            system_prompt=system_prompt,
+            stage="followup_answer",
+            attachments=attachments,
+            trace_meta=build_trace_metadata(
+                call_id=new_call_id(
+                    f"quiz-followup-{question_context.get('question_id', 'question')}"
+                ),
+                phase="generation",
+                label=f"Answer follow-up for {self._humanize_question_id(question_context.get('question_id', 'question'))}",
+                call_kind="llm_generation",
+                trace_id=str(question_context.get("question_id", "question")),
+                question_id=str(question_context.get("question_id", "")),
+            ),
+        ):
+            _chunks.append(_c)
+        return "".join(_chunks)
+
+    @staticmethod
+    def _humanize_question_id(question_id: Any) -> str:
+        raw = str(question_id or "").strip()
+        if raw.lower().startswith("q_") and raw[2:].isdigit():
+            return f"Question {raw[2:]}"
+        return raw or "question"
+
+    @staticmethod
+    def _render_question_context(question_context: dict[str, Any]) -> str:
+        options = question_context.get("options") or {}
+        option_lines: list[str] = []
+        if isinstance(options, dict):
+            for key, value in options.items():
+                if str(value or "").strip():
+                    option_lines.append(f"{key}. {value}")
+
+        correctness = question_context.get("is_correct")
+        correctness_text = (
+            "correct" if correctness is True else "incorrect" if correctness is False else "unknown"
+        )
+
+        lines = [
+            f"Question ID: {question_context.get('question_id') or '(none)'}",
+            f"Question type: {question_context.get('question_type') or '(none)'}",
+            f"Difficulty: {question_context.get('difficulty') or '(none)'}",
+            f"Concentration: {question_context.get('concentration') or '(none)'}",
+            "",
+            "Question:",
+            str(question_context.get("question", "") or "(none)"),
+        ]
+        if option_lines:
+            lines.extend(["", "Options:", *option_lines])
+        lines.extend(
+            [
+                "",
+                f"Learner answer: {question_context.get('user_answer') or '(not provided)'}",
+                f"Learner result: {correctness_text}",
+                f"Reference answer: {question_context.get('correct_answer') or '(none)'}",
+                "",
+                "Explanation:",
+                str(question_context.get("explanation", "") or "(none)"),
+            ]
+        )
+        knowledge_context = str(question_context.get("knowledge_context", "") or "").strip()
+        if knowledge_context:
+            lines.extend(["", "Knowledge context:", knowledge_context])
+        return "\n".join(lines).strip()

deeptutor/agents/question/capability.py

@@ -0,0 +1,465 @@
+"""Deep Question Capability.
+
+Routes one user turn through the right quiz-generation path:
+
+* followup — single-call ``FollowupAgent`` reply about one prior question.
+* custom mode — new ``QuestionPipeline`` (explore → plan → per-question loop).
+* mimic mode  — same pipeline, but PDF parsing produces the templates
+  and ``templates_override`` skips explore + plan.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+from pathlib import Path
+import tempfile
+from typing import Any
+
+from deeptutor.agents._shared.capability_result import emit_capability_result
+from deeptutor.core.capability_protocol import TurnCapability
+from deeptutor.core.context import UnifiedContext
+from deeptutor.core.trace import merge_trace_metadata
+from deeptutor.i18n import StatusI18n
+from deeptutor.runtime.agentic.usage import UsageTracker
+from deeptutor.runtime.bootstrap.builtin_capabilities import builtin_capability_manifest
+from deeptutor.runtime.stream_bus import StreamBus
+
+
+class DeepQuestionCapability(TurnCapability):
+    manifest = builtin_capability_manifest("deep_question")
+
+    async def run(self, context: UnifiedContext, stream: StreamBus) -> None:
+        from deeptutor.services.llm.config import get_llm_config
+
+        llm_config = get_llm_config()
+        kb_name = context.knowledge_bases[0] if context.knowledge_bases else None
+        turn_id = str(context.metadata.get("turn_id", "") or context.session_id or "deep-question")
+        i18n = StatusI18n(self.name, context.language, module="question")
+
+        overrides = context.config_overrides
+        mode = str(overrides.get("mode", "custom") or "custom").strip().lower()
+        topic = str(overrides.get("topic") or context.user_message or "").strip()
+        # Validate user-fixable input before allocating a workspace or invoking
+        # any provider/parser.  This keeps an empty custom request from
+        # surfacing a low-level filesystem error such as ``Operation not
+        # permitted``.
+        if mode == "custom" and not topic:
+            await stream.error(
+                i18n.t(
+                    "topic_required",
+                    "Please provide a topic before generating questions.",
+                ),
+                source=self.name,
+                metadata={"code": "topic_required", "retryable": True},
+            )
+            return
+        runtime_workspace = context.runtime.workspace
+        if runtime_workspace is not None:
+            output_dir = Path(runtime_workspace.output_dir) / "question_generation"
+            output_dir.mkdir(parents=True, exist_ok=True)
+        else:
+            # Direct legacy callers that do not construct a TurnRuntimeContext
+            # retain their historical storage path.
+            from deeptutor.services.path_service import get_path_service
+
+            output_dir = get_path_service().get_task_workspace("deep_question", turn_id)
+        followup_question_context = context.metadata.get("question_followup_context", {}) or {}
+        if isinstance(followup_question_context, dict) and followup_question_context.get(
+            "question"
+        ):
+            from deeptutor.agents.question.agents.followup_agent import FollowupAgent
+
+            usage = UsageTracker(model=getattr(llm_config, "model", None))
+            agent = FollowupAgent(
+                language=context.language,
+                api_key=llm_config.api_key,
+                base_url=llm_config.base_url,
+                api_version=llm_config.api_version,
+                token_tracker=usage,
+            )
+            agent.set_trace_callback(self._build_trace_bridge(stream, i18n=i18n))
+            async with stream.stage("generation", source=self.name):
+                answer = await agent.process(
+                    user_message=context.user_message,
+                    question_context=followup_question_context,
+                    history_context=str(
+                        context.metadata.get("conversation_context_text", "") or ""
+                    ).strip(),
+                    attachments=context.attachments,
+                )
+                if answer:
+                    await stream.content(answer, source=self.name, stage="generation")
+                followup_payload: dict[str, Any] = {
+                    "response": answer or "",
+                    "mode": "followup",
+                    "question_id": followup_question_context.get("question_id", ""),
+                }
+                await emit_capability_result(
+                    stream, followup_payload, source=self.name, usage=usage
+                )
+            return
+
+        mode = str(overrides.get("mode", "custom") or "custom").strip().lower()
+        topic = str(overrides.get("topic") or context.user_message or "").strip()
+        num_questions = int(overrides.get("num_questions", 1) or 1)
+        difficulty = str(overrides.get("difficulty", "") or "")
+        raw_types = overrides.get("question_types") or []
+        question_types = list(raw_types) if isinstance(raw_types, list) else []
+        raw_counts = overrides.get("per_type_counts") or {}
+        per_type_counts = (
+            {str(k): int(v) for k, v in raw_counts.items() if isinstance(v, int) and v > 0}
+            if isinstance(raw_counts, dict)
+            else {}
+        )
+        history_context = str(context.metadata.get("conversation_context_text", "") or "").strip()
+
+        if mode != "mimic":
+            # New custom-mode pipeline: explore → plan → per-question quiz loop.
+            # The pipeline owns its own stream.content / stream.result emission;
+            # nothing here to render afterwards.
+            from deeptutor.agents.question.history import load_session_quiz_history
+            from deeptutor.agents.question.pipeline import QuestionPipeline
+            from deeptutor.agents.question.request_config import (
+                build_question_runtime_config,
+            )
+            from deeptutor.services.config import load_config_with_main
+
+            if not topic:
+                await stream.error(
+                    i18n.t(
+                        "topic_required",
+                        "Topic is required for custom question generation.",
+                    ),
+                    source=self.name,
+                )
+                return
+
+            quiz_history = await load_session_quiz_history(context.session_id or "")
+            runtime_config = build_question_runtime_config(
+                base_config=load_config_with_main("main.yaml"),
+            )
+            pipeline = QuestionPipeline(
+                language=context.language,
+                kb_name=kb_name,
+                enabled_tools=list(context.enabled_tools or []),
+                runtime_config=runtime_config,
+            )
+            await pipeline.run(
+                context=context,
+                user_message=topic,
+                num_questions=num_questions,
+                difficulty=difficulty,
+                question_types=question_types,
+                per_type_counts=per_type_counts,
+                conversation_context=history_context,
+                attachments=context.attachments,
+                quiz_history=quiz_history,
+                stream=stream,
+            )
+            return
+
+        # Mimic mode — also runs through QuestionPipeline, but parses the
+        # exam paper into templates first and passes them via
+        # ``templates_override`` so explore + plan are skipped.
+        await self._run_mimic_mode(
+            context=context,
+            stream=stream,
+            kb_name=kb_name,
+            output_dir=output_dir,
+            overrides=overrides,
+            history_context=history_context,
+            num_questions=num_questions,
+            i18n=i18n,
+        )
+
+    async def _run_mimic_mode(
+        self,
+        *,
+        context: UnifiedContext,
+        stream: StreamBus,
+        kb_name: str | None,
+        output_dir,
+        overrides: dict[str, Any],
+        history_context: str,
+        num_questions: int,
+        i18n: StatusI18n | None = None,
+    ) -> None:
+        """Resolve an exam paper → templates → ``QuestionPipeline.run`` with
+        ``templates_override``. No legacy AgentCoordinator involvement.
+
+        Three input shapes:
+
+        * Uploaded PDF attachment      → write to tmpfile, parse with MinerU
+        * Server-side parsed directory → skip parsing, just extract questions
+        * ``[Attached Documents]`` in  → no paper available; fall back to
+          the user_message text          custom-mode pipeline with a
+                                         "mimic the attached source" hint
+                                         prefixed onto the user_message
+        """
+        from deeptutor.agents.question.history import load_session_quiz_history
+        from deeptutor.agents.question.mimic_source import (
+            parse_exam_paper_to_templates,
+        )
+        from deeptutor.agents.question.pipeline import QuestionPipeline
+        from deeptutor.agents.question.request_config import (
+            build_question_runtime_config,
+        )
+        from deeptutor.services.config import load_config_with_main
+        from deeptutor.services.parsing.engines.mineru.config import MinerUError
+
+        if i18n is None:
+            i18n = StatusI18n(self.name, context.language, module="question")
+        paper_path = str(overrides.get("paper_path", "") or "").strip()
+        max_questions = int(overrides.get("max_questions", 10) or 10)
+        pdf_attachment = next(
+            (
+                attachment
+                for attachment in context.attachments
+                if attachment.filename.lower().endswith(".pdf")
+                or attachment.type == "pdf"
+                or attachment.mime_type == "application/pdf"
+            ),
+            None,
+        )
+
+        runtime_config = build_question_runtime_config(
+            base_config=load_config_with_main("main.yaml"),
+        )
+        pipeline = QuestionPipeline(
+            language=context.language,
+            kb_name=kb_name,
+            enabled_tools=list(context.enabled_tools or []),
+            runtime_config=runtime_config,
+        )
+        quiz_history = await load_session_quiz_history(context.session_id or "")
+
+        async def _emit_parse_notice(message: str) -> None:
+            async with stream.stage("exploring", source=self.name):
+                await stream.thinking(message, source=self.name, stage="exploring")
+
+        if pdf_attachment and pdf_attachment.base64:
+            # Bridge MinerU's progress lines (emitted from the parser worker
+            # thread) back onto the event loop so the trace panel streams them
+            # live — model downloads and per-page parsing would otherwise look
+            # like a silent multi-minute hang.
+            loop = asyncio.get_running_loop()
+
+            def _parse_progress(line: str) -> None:
+                asyncio.run_coroutine_threadsafe(
+                    stream.thinking(line, source=self.name, stage="exploring"),
+                    loop,
+                )
+
+            try:
+                async with stream.stage("exploring", source=self.name):
+                    await stream.thinking(
+                        i18n.t(
+                            "parsing_uploaded",
+                            "Parsing uploaded exam paper and extracting templates...",
+                        ),
+                        source=self.name,
+                        stage="exploring",
+                    )
+                    with tempfile.NamedTemporaryFile(suffix=".pdf", delete=True) as temp_pdf:
+                        temp_pdf.write(base64.b64decode(pdf_attachment.base64))
+                        temp_pdf.flush()
+                        templates, _ = await parse_exam_paper_to_templates(
+                            temp_pdf.name,
+                            max_questions=max_questions,
+                            paper_mode="upload",
+                            output_dir=output_dir,
+                            progress_callback=_parse_progress,
+                        )
+            except MinerUError as exc:
+                await stream.error(str(exc), source=self.name)
+                return
+            await pipeline.run(
+                context=context,
+                user_message=context.user_message,
+                num_questions=len(templates) or num_questions,
+                difficulty="",
+                conversation_context=history_context,
+                attachments=context.attachments,
+                quiz_history=quiz_history,
+                templates_override=templates,
+                stream=stream,
+            )
+            return
+
+        if paper_path:
+            await _emit_parse_notice(
+                i18n.t(
+                    "parsing_directory",
+                    "Loading parsed exam paper and extracting templates...",
+                )
+            )
+            try:
+                templates, _ = await parse_exam_paper_to_templates(
+                    paper_path,
+                    max_questions=max_questions,
+                    paper_mode="parsed",
+                    output_dir=output_dir,
+                )
+            except MinerUError as exc:
+                await stream.error(str(exc), source=self.name)
+                return
+            await pipeline.run(
+                context=context,
+                user_message=context.user_message,
+                num_questions=len(templates) or num_questions,
+                difficulty="",
+                conversation_context=history_context,
+                attachments=context.attachments,
+                quiz_history=quiz_history,
+                templates_override=templates,
+                stream=stream,
+            )
+            return
+
+        if "[Attached Documents]" in context.user_message:
+            # No paper available — degrade to custom-mode generation but
+            # bias the pipeline toward shadowing the attached source by
+            # prefixing the user message with an explicit instruction.
+            mimic_hint = (
+                "[Mimic the attached source document as closely as possible: "
+                "style, difficulty, structure, and assessed concepts.]\n\n"
+            )
+            await pipeline.run(
+                context=context,
+                user_message=mimic_hint + context.user_message,
+                num_questions=max_questions,
+                difficulty="",
+                conversation_context=history_context,
+                attachments=context.attachments,
+                quiz_history=quiz_history,
+                stream=stream,
+            )
+            return
+
+        await stream.error(
+            i18n.t(
+                "mimic_needs_paper",
+                "Mimic mode requires either an uploaded PDF or a parsed exam directory.",
+            ),
+            source=self.name,
+        )
+
+    def _build_trace_bridge(self, stream: StreamBus, i18n: StatusI18n | None = None):
+        async def _trace_bridge(update: dict[str, Any]) -> None:
+            event = str(update.get("event", "") or "")
+            stage = str(update.get("phase") or update.get("stage") or "generation")
+            base_metadata = {
+                key: value
+                for key, value in update.items()
+                if key
+                not in {"event", "state", "response", "chunk", "result", "tool_name", "tool_args"}
+            }
+
+            if event == "llm_call":
+                state = str(update.get("state", "running"))
+                label = str(update.get("label", "") or "")
+                if state == "running":
+                    await stream.progress(
+                        message=label,
+                        source=self.name,
+                        stage=stage,
+                        metadata=merge_trace_metadata(
+                            base_metadata,
+                            {"trace_kind": "call_status", "call_state": "running"},
+                        ),
+                    )
+                    return
+                if state == "streaming":
+                    chunk = str(update.get("chunk", "") or "")
+                    if chunk:
+                        await stream.thinking(
+                            chunk,
+                            source=self.name,
+                            stage=stage,
+                            metadata=merge_trace_metadata(
+                                base_metadata,
+                                {"trace_kind": "llm_chunk"},
+                            ),
+                        )
+                    return
+                if state == "complete":
+                    was_streaming = update.get("streaming", False)
+                    if not was_streaming:
+                        response = str(update.get("response", "") or "")
+                        if response:
+                            await stream.thinking(
+                                response,
+                                source=self.name,
+                                stage=stage,
+                                metadata=merge_trace_metadata(
+                                    base_metadata,
+                                    {"trace_kind": "llm_output"},
+                                ),
+                            )
+                    await stream.progress(
+                        message="",
+                        source=self.name,
+                        stage=stage,
+                        metadata=merge_trace_metadata(
+                            base_metadata,
+                            {"trace_kind": "call_status", "call_state": "complete"},
+                        ),
+                    )
+                    return
+                if state == "error":
+                    fallback = (
+                        i18n.t("llm_call_failed", "LLM call failed.")
+                        if i18n is not None
+                        else "LLM call failed."
+                    )
+                    await stream.error(
+                        str(update.get("response", "") or fallback),
+                        source=self.name,
+                        stage=stage,
+                        metadata=merge_trace_metadata(
+                            base_metadata,
+                            {"trace_kind": "call_status", "call_state": "error"},
+                        ),
+                    )
+                    return
+
+            if event == "tool_call":
+                await stream.tool_call(
+                    tool_name=str(update.get("tool_name", "") or "tool"),
+                    args=update.get("tool_args", {}) or {},
+                    source=self.name,
+                    stage=stage,
+                    metadata=merge_trace_metadata(
+                        base_metadata,
+                        {"trace_kind": "tool_call"},
+                    ),
+                )
+                return
+
+            if event == "tool_result":
+                state = str(update.get("state", "complete"))
+                result = str(update.get("result", "") or "")
+                if state == "error":
+                    await stream.error(
+                        result,
+                        source=self.name,
+                        stage=stage,
+                        metadata=merge_trace_metadata(
+                            base_metadata,
+                            {"trace_kind": "tool_result"},
+                        ),
+                    )
+                    return
+                await stream.tool_result(
+                    tool_name=str(update.get("tool_name", "") or "tool"),
+                    result=result,
+                    source=self.name,
+                    stage=stage,
+                    metadata=merge_trace_metadata(
+                        base_metadata,
+                        {"trace_kind": "tool_result"},
+                    ),
+                )
+
+        return _trace_bridge