deeptutor-renderer-manim 1.7.0__py3-none-any.whl

deeptutor/agents/math_animator/__init__.py

@@ -0,0 +1,23 @@
+"""Math animator agents and pipeline."""
+
+from importlib import import_module
+from typing import Any
+
+from .request_config import (
+    MathAnimatorRequestConfig,
+    validate_math_animator_request_config,
+)
+
+__all__ = [
+    "MathAnimatorPipeline",
+    "MathAnimatorRequestConfig",
+    "validate_math_animator_request_config",
+]
+
+
+def __getattr__(name: str) -> Any:
+    if name == "MathAnimatorPipeline":
+        value = import_module(f"{__name__}.pipeline").MathAnimatorPipeline
+        globals()[name] = value
+        return value
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

deeptutor/agents/math_animator/agents/__init__.py

@@ -0,0 +1,15 @@
+"""Agent building blocks for the math animator capability."""
+
+from .code_generator_agent import CodeGeneratorAgent
+from .concept_analysis_agent import ConceptAnalysisAgent
+from .concept_design_agent import ConceptDesignAgent
+from .summary_agent import SummaryAgent
+from .visual_review_agent import VisualReviewAgent
+
+__all__ = [
+    "CodeGeneratorAgent",
+    "ConceptAnalysisAgent",
+    "ConceptDesignAgent",
+    "SummaryAgent",
+    "VisualReviewAgent",
+]

deeptutor/agents/math_animator/agents/code_generator_agent.py

@@ -0,0 +1,268 @@
+"""Code generation and repair stages for math animator."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+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.llm import StreamOutcome
+from deeptutor.services.llm.reasoning_params import RETRY_REASONING_EFFORT
+
+from ..models import ConceptAnalysis, GeneratedCode, SceneDesign
+from ..utils import (
+    build_repair_error_message,
+    describe_unusable_output,
+    escalated_max_tokens,
+    extract_json_object,
+)
+
+#: How much of a failed response to keep in the debug log. Enough to see where
+#: a truncated generation stopped, short enough to stay readable (#1545).
+_RAW_EXCERPT_CHARS = 200
+
+
+class GeneratedCodeOutputError(ValueError):
+    """The model exhausted its retries without returning runnable code."""
+
+
+class CodeGeneratorAgent(BaseAgent):
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        api_version: str | None = None,
+        language: str = "zh",
+    ) -> None:
+        super().__init__(
+            module_name="math_animator",
+            agent_name="code_generator_agent",
+            api_key=api_key,
+            base_url=base_url,
+            api_version=api_version,
+            language=language,
+        )
+
+    async def process(
+        self,
+        *,
+        user_input: str,
+        output_mode: str,
+        analysis: ConceptAnalysis,
+        design: SceneDesign,
+        duration_target_seconds: float | None = None,
+    ) -> GeneratedCode:
+        """BaseAgent-compatible entrypoint for the default generation path."""
+        return await self.generate(
+            user_input=user_input,
+            output_mode=output_mode,
+            analysis=analysis,
+            design=design,
+            duration_target_seconds=duration_target_seconds,
+        )
+
+    async def generate(
+        self,
+        *,
+        user_input: str,
+        output_mode: str,
+        analysis: ConceptAnalysis,
+        design: SceneDesign,
+        duration_target_seconds: float | None = None,
+    ) -> GeneratedCode:
+        system_prompt = self.get_prompt("generate_system")
+        user_template = self.get_prompt("generate_user_template")
+        if not system_prompt or not user_template:
+            raise ValueError("CodeGeneratorAgent generation prompts are not configured.")
+
+        user_prompt = user_template.format(
+            user_input=user_input.strip(),
+            output_mode=output_mode,
+            duration_requirement=(
+                f"用户明确目标时长约 {duration_target_seconds:.1f} 秒，生成代码必须围绕该时长做节奏预算。"
+                if duration_target_seconds is not None
+                else "用户未给出明确秒数时长，可按标准教学节奏生成。"
+            ),
+            analysis_json=json.dumps(analysis.model_dump(), ensure_ascii=False, indent=2),
+            design_json=json.dumps(design.model_dump(), ensure_ascii=False, indent=2),
+        )
+        return await self._request_generated_code(
+            user_prompt=user_prompt,
+            system_prompt=system_prompt,
+            stage="code_generation",
+            call_id_prefix="math-codegen",
+            trace_meta={
+                "phase": "code_generation",
+                "label": "Code generation",
+                "call_kind": "math_code_generation",
+                "trace_role": "generate",
+                "trace_kind": "llm_output",
+            },
+        )
+
+    async def repair(
+        self,
+        *,
+        user_input: str,
+        output_mode: str,
+        current_code: str,
+        error_message: str,
+        attempt: int,
+        duration_target_seconds: float | None = None,
+    ) -> GeneratedCode:
+        system_prompt = self.get_prompt("retry_system")
+        user_template = self.get_prompt("retry_user_template")
+        if not system_prompt or not user_template:
+            raise ValueError("CodeGeneratorAgent retry prompts are not configured.")
+
+        user_prompt = user_template.format(
+            user_input=user_input.strip(),
+            output_mode=output_mode,
+            attempt=attempt,
+            duration_requirement=(
+                f"目标时长约 {duration_target_seconds:.1f} 秒，修复后仍需保持接近该时长。"
+                if duration_target_seconds is not None
+                else "无明确目标时长。"
+            ),
+            error_message=build_repair_error_message(error_message),
+            current_code=current_code,
+        )
+        return await self._request_generated_code(
+            user_prompt=user_prompt,
+            system_prompt=system_prompt,
+            stage="code_retry",
+            call_id_prefix="math-retry",
+            trace_meta={
+                "phase": "code_retry",
+                "label": f"Code retry #{attempt}",
+                "call_kind": "math_code_retry",
+                "trace_role": "repair",
+                "trace_kind": "llm_output",
+                "attempt": attempt,
+            },
+        )
+
+    async def _request_generated_code(
+        self,
+        *,
+        user_prompt: str,
+        system_prompt: str,
+        stage: str,
+        call_id_prefix: str,
+        trace_meta: dict[str, Any],
+    ) -> GeneratedCode:
+        """Retry model-success responses that contain no usable code.
+
+        Provider retries already cover transport failures.  This second,
+        deliberately narrow boundary covers a successful response whose
+        content is blank, reasoning-only, or malformed JSON (#1202).  Parsing
+        stays strict and callers never proceed to the renderer with ``code=''``.
+
+        A retry is not a repeat.  The provider reports whether it stopped at the
+        output cap, and a reasoning model that spent the whole budget on
+        chain-of-thought fails that way every time on the same request (#1547),
+        so a truncated attempt is retried with a larger budget and lower
+        reasoning effort. Whichever way the attempt failed, the
+        reason reaches both the log and the raised error (#1545).
+        """
+
+        max_retries = max(0, int(self.get_max_retries()))
+        base_max_tokens = max(0, int(self.get_max_tokens() or 0))
+        attempts = max_retries + 1
+        last_error: Exception | None = None
+        last_failure = ""
+        truncations = 0
+        for structured_attempt in range(attempts):
+            max_tokens = escalated_max_tokens(base_max_tokens, truncations)
+            retry_instruction = self._retry_instruction(
+                attempt=structured_attempt, after_truncation=truncations > 0
+            )
+            outcome = StreamOutcome()
+            chunks: list[str] = []
+            async for chunk in self.stream_llm(
+                user_prompt=user_prompt + retry_instruction,
+                system_prompt=system_prompt,
+                response_format={"type": "json_object"},
+                max_tokens=max_tokens or None,
+                reasoning_effort=(RETRY_REASONING_EFFORT if structured_attempt else None),
+                stage=stage,
+                trace_meta=build_trace_metadata(
+                    call_id=new_call_id(call_id_prefix),
+                    **trace_meta,
+                    structured_attempt=structured_attempt + 1,
+                ),
+                outcome=outcome,
+            ):
+                chunks.append(chunk)
+            raw_response = "".join(chunks)
+
+            try:
+                generated = GeneratedCode.model_validate(extract_json_object(raw_response))
+                if not generated.code.strip():
+                    raise ValueError("structured response has an empty code field")
+                return generated
+            except (json.JSONDecodeError, ValueError) as exc:
+                last_error = exc
+                last_failure = describe_unusable_output(
+                    error=exc,
+                    raw_response=raw_response,
+                    outcome=outcome,
+                    max_tokens=max_tokens,
+                )
+                if outcome.truncated:
+                    truncations += 1
+                self.logger.warning(
+                    "Math animator %s attempt %d/%d produced no usable code: %s",
+                    stage,
+                    structured_attempt + 1,
+                    attempts,
+                    last_failure,
+                )
+                self.logger.debug(
+                    "Math animator %s attempt %d raw response head=%r tail=%r",
+                    stage,
+                    structured_attempt + 1,
+                    raw_response[:_RAW_EXCERPT_CHARS],
+                    raw_response[-_RAW_EXCERPT_CHARS:],
+                )
+                if structured_attempt >= max_retries:
+                    break
+                # Once the budget cannot grow, another truncated call repeats
+                # the same failure instead of repairing it (#1914).
+                if (
+                    outcome.truncated
+                    and escalated_max_tokens(base_max_tokens, truncations) <= max_tokens
+                ):
+                    break
+                await asyncio.sleep(min(0.25 * (2**structured_attempt), 2.0))
+
+        raise GeneratedCodeOutputError(
+            f"Math animator {stage} returned no usable code after {structured_attempt + 1} attempts. "
+            f"Last attempt: {last_failure}"
+        ) from last_error
+
+    @staticmethod
+    def _retry_instruction(*, attempt: int, after_truncation: bool) -> str:
+        """The nudge appended to the prompt on retry, matched to the failure."""
+
+        if not attempt:
+            return ""
+        if after_truncation:
+            # Asking again for "structured code" is useless when the previous
+            # response was a complete thought and an incomplete answer: the
+            # budget, not the format, is what ran out (#1547).
+            return (
+                "\n\nYour previous response hit the output token limit before the JSON "
+                "was complete. Keep your internal reasoning to a few sentences and spend "
+                "the budget on the code itself. Return exactly one JSON object with a "
+                "non-empty `code` field and nothing else."
+            )
+        return (
+            "\n\nYour previous response contained no usable structured code. "
+            "Return exactly one JSON object with a non-empty `code` field."
+        )
+
+
+__all__ = ["CodeGeneratorAgent", "GeneratedCodeOutputError"]

deeptutor/agents/math_animator/agents/concept_analysis_agent.py

@@ -0,0 +1,97 @@
+"""Concept analysis stage for math animator."""
+
+from __future__ import annotations
+
+from deeptutor.agents.base_agent import BaseAgent
+from deeptutor.core.context import Attachment
+from deeptutor.core.trace import build_trace_metadata, new_call_id
+from deeptutor.services.llm.structured_retry import json_with_reasoning_retry
+from deeptutor.services.prompt import get_prompt_manager
+
+from ..models import ConceptAnalysis
+
+
+class ConceptAnalysisAgent(BaseAgent):
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        api_version: str | None = None,
+        language: str = "zh",
+    ) -> None:
+        super().__init__(
+            module_name="math_animator",
+            agent_name="concept_analysis_agent",
+            api_key=api_key,
+            base_url=base_url,
+            api_version=api_version,
+            language=language,
+        )
+
+    async def process(
+        self,
+        *,
+        user_input: str,
+        history_context: str,
+        output_mode: str,
+        style_hint: str,
+        attachments: list[Attachment],
+    ) -> ConceptAnalysis:
+        system_prompt = self.get_prompt("system")
+        user_template = self.get_prompt("user_template")
+        if not system_prompt or not user_template:
+            # Retry once: a worker that looked the prompts up before the
+            # package finished installing used to cache the empty result
+            # forever. PromptManager no longer caches misses, so a reload can
+            # now actually recover — and it stays the one place that knows how
+            # to find a prompt file.
+            self.prompts = get_prompt_manager().reload_prompts(
+                "math_animator", "concept_analysis_agent", self.language
+            )
+            system_prompt = self.get_prompt("system")
+            user_template = self.get_prompt("user_template")
+
+        if not system_prompt or not user_template:
+            raise ValueError("ConceptAnalysisAgent prompts are not configured.")
+
+        reference_count = sum(1 for item in attachments if item.type == "image")
+        user_prompt = user_template.format(
+            user_input=user_input.strip(),
+            history_context=history_context.strip() or "(none)",
+            output_mode=output_mode,
+            style_hint=style_hint.strip() or "(none)",
+            reference_count=reference_count,
+        )
+        messages = [
+            {"role": "system", "content": system_prompt},
+            {"role": "user", "content": user_prompt},
+        ]
+
+        async def _run(reasoning_effort: str | None) -> str:
+            chunks: list[str] = []
+            async for chunk in self.stream_llm(
+                user_prompt=user_prompt,
+                system_prompt=system_prompt,
+                messages=messages,
+                attachments=attachments,
+                response_format={"type": "json_object"},
+                reasoning_effort=reasoning_effort,
+                stage="concept_analysis",
+                trace_meta=build_trace_metadata(
+                    call_id=new_call_id("math-analysis"),
+                    phase="concept_analysis",
+                    label="Concept analysis",
+                    call_kind="math_concept_analysis",
+                    trace_role="analyze",
+                    trace_kind="llm_output",
+                ),
+            ):
+                chunks.append(chunk)
+            return "".join(chunks)
+
+        payload = await json_with_reasoning_retry(
+            _run, expected_key="learning_goal", logger_instance=self.logger
+        )
+        if not payload.get("learning_goal"):
+            raise ValueError("Math animator concept analysis returned no learning goal.")
+        return ConceptAnalysis.model_validate(payload)

deeptutor/agents/math_animator/agents/concept_design_agent.py

@@ -0,0 +1,76 @@
+"""Concept design stage for math animator."""
+
+from __future__ import annotations
+
+import json
+
+from deeptutor.agents.base_agent import BaseAgent
+from deeptutor.core.trace import build_trace_metadata, new_call_id
+from deeptutor.services.llm.structured_retry import json_with_reasoning_retry
+
+from ..models import ConceptAnalysis, SceneDesign
+
+
+class ConceptDesignAgent(BaseAgent):
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        api_version: str | None = None,
+        language: str = "zh",
+    ) -> None:
+        super().__init__(
+            module_name="math_animator",
+            agent_name="concept_design_agent",
+            api_key=api_key,
+            base_url=base_url,
+            api_version=api_version,
+            language=language,
+        )
+
+    async def process(
+        self,
+        *,
+        user_input: str,
+        output_mode: str,
+        analysis: ConceptAnalysis,
+        style_hint: str,
+    ) -> SceneDesign:
+        system_prompt = self.get_prompt("system")
+        user_template = self.get_prompt("user_template")
+        if not system_prompt or not user_template:
+            raise ValueError("ConceptDesignAgent prompts are not configured.")
+
+        user_prompt = user_template.format(
+            user_input=user_input.strip(),
+            output_mode=output_mode,
+            style_hint=style_hint.strip() or "(none)",
+            analysis_json=json.dumps(analysis.model_dump(), ensure_ascii=False, indent=2),
+        )
+
+        async def _run(reasoning_effort: str | None) -> str:
+            chunks: list[str] = []
+            async for chunk in self.stream_llm(
+                user_prompt=user_prompt,
+                system_prompt=system_prompt,
+                response_format={"type": "json_object"},
+                reasoning_effort=reasoning_effort,
+                stage="concept_design",
+                trace_meta=build_trace_metadata(
+                    call_id=new_call_id("math-design"),
+                    phase="concept_design",
+                    label="Concept design",
+                    call_kind="math_concept_design",
+                    trace_role="design",
+                    trace_kind="llm_output",
+                ),
+            ):
+                chunks.append(chunk)
+            return "".join(chunks)
+
+        payload = await json_with_reasoning_retry(
+            _run, expected_key="scene_outline", logger_instance=self.logger
+        )
+        if not payload.get("scene_outline"):
+            raise ValueError("Math animator concept design returned no scene outline.")
+        return SceneDesign.model_validate(payload)

deeptutor/agents/math_animator/agents/summary_agent.py

@@ -0,0 +1,78 @@
+"""Summary stage for math animator."""
+
+from __future__ import annotations
+
+import json
+
+from deeptutor.agents.base_agent import BaseAgent
+from deeptutor.core.trace import build_trace_metadata, new_call_id
+from deeptutor.services.llm.structured_retry import json_with_reasoning_retry
+
+from ..models import ConceptAnalysis, RenderResult, SceneDesign, SummaryPayload
+
+
+class SummaryAgent(BaseAgent):
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        api_version: str | None = None,
+        language: str = "zh",
+    ) -> None:
+        super().__init__(
+            module_name="math_animator",
+            agent_name="summary_agent",
+            api_key=api_key,
+            base_url=base_url,
+            api_version=api_version,
+            language=language,
+        )
+
+    async def process(
+        self,
+        *,
+        user_input: str,
+        output_mode: str,
+        analysis: ConceptAnalysis,
+        design: SceneDesign,
+        render_result: RenderResult,
+    ) -> SummaryPayload:
+        system_prompt = self.get_prompt("system")
+        user_template = self.get_prompt("user_template")
+        if not system_prompt or not user_template:
+            raise ValueError("SummaryAgent prompts are not configured.")
+
+        user_prompt = user_template.format(
+            user_input=user_input.strip(),
+            output_mode=output_mode,
+            analysis_json=json.dumps(analysis.model_dump(), ensure_ascii=False, indent=2),
+            design_json=json.dumps(design.model_dump(), ensure_ascii=False, indent=2),
+            render_json=json.dumps(render_result.model_dump(), ensure_ascii=False, indent=2),
+        )
+
+        async def _run(reasoning_effort: str | None) -> str:
+            chunks: list[str] = []
+            async for chunk in self.stream_llm(
+                user_prompt=user_prompt,
+                system_prompt=system_prompt,
+                response_format={"type": "json_object"},
+                reasoning_effort=reasoning_effort,
+                stage="summary",
+                trace_meta=build_trace_metadata(
+                    call_id=new_call_id("math-summary"),
+                    phase="summary",
+                    label="Summarize result",
+                    call_kind="math_summary",
+                    trace_role="summarize",
+                    trace_kind="llm_output",
+                ),
+            ):
+                chunks.append(chunk)
+            return "".join(chunks)
+
+        payload = await json_with_reasoning_retry(
+            _run, expected_key="summary_text", logger_instance=self.logger
+        )
+        # Rendering has already succeeded. Keep returning its artifacts if the
+        # summary remains empty after the low-effort retry.
+        return SummaryPayload.model_validate(payload)

deeptutor/agents/math_animator/agents/visual_review_agent.py

@@ -0,0 +1,100 @@
+"""Visual quality review stage for math animator outputs."""
+
+from __future__ import annotations
+
+import json
+
+from deeptutor.agents.base_agent import BaseAgent
+from deeptutor.core.context import Attachment
+from deeptutor.core.trace import build_trace_metadata, new_call_id
+from deeptutor.services.llm import supports_vision
+
+from ..models import RenderResult, VisualReviewResult
+from ..utils import extract_json_object
+
+
+class VisualReviewAgent(BaseAgent):
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        api_version: str | None = None,
+        language: str = "zh",
+    ) -> None:
+        super().__init__(
+            module_name="math_animator",
+            agent_name="visual_review_agent",
+            api_key=api_key,
+            base_url=base_url,
+            api_version=api_version,
+            language=language,
+        )
+
+    async def process(
+        self,
+        *,
+        user_input: str,
+        output_mode: str,
+        current_code: str,
+        render_result: RenderResult,
+        attachments: list[Attachment],
+    ) -> VisualReviewResult:
+        if not attachments:
+            return VisualReviewResult(
+                passed=True,
+                summary="Visual review skipped because no review frames were available.",
+                reviewed_frames=0,
+            )
+
+        model = self.get_model()
+        if not supports_vision(self.binding, model):
+            return VisualReviewResult(
+                passed=True,
+                summary="Visual review skipped because the current model does not support image inspection.",
+                reviewed_frames=len(attachments),
+            )
+
+        system_prompt = self.get_prompt("system")
+        user_template = self.get_prompt("user_template")
+        if not system_prompt or not user_template:
+            raise ValueError("VisualReviewAgent prompts are not configured.")
+
+        user_prompt = user_template.format(
+            user_input=user_input.strip(),
+            output_mode=output_mode,
+            reviewed_frames=len(attachments),
+            render_json=json.dumps(
+                render_result.model_dump(exclude={"visual_review"}), ensure_ascii=False, indent=2
+            ),
+            current_code=current_code,
+        )
+        messages = [
+            {"role": "system", "content": system_prompt},
+            {"role": "user", "content": user_prompt},
+        ]
+        _chunks: list[str] = []
+        async for _c in self.stream_llm(
+            user_prompt=user_prompt,
+            system_prompt=system_prompt,
+            messages=messages,
+            attachments=attachments,
+            response_format={"type": "json_object"},
+            model=model,
+            stage="render_output",
+            trace_meta=build_trace_metadata(
+                call_id=new_call_id("math-visual-review"),
+                phase="render_output",
+                label="Visual quality review",
+                call_kind="math_visual_review",
+                trace_role="review",
+                trace_kind="llm_output",
+            ),
+        ):
+            _chunks.append(_c)
+        response = "".join(_chunks)
+        payload = extract_json_object(response)
+        payload.setdefault("reviewed_frames", len(attachments))
+        return VisualReviewResult.model_validate(payload)
+
+
+__all__ = ["VisualReviewAgent"]