HKUDS/DeepTutor · error · GenerationFailure

AnimationGenerator requires the optional math-animator extra

Error message

AnimationGenerator requires the optional math-animator extras. Install with `pip install -e '.[math-animator]'` or `pip install -r requirements/math-animator.txt`.

What it means

The ANIMATION book block requires Manim, provided only via the optional `math-animator` extra. `_generate` checks `importlib.util.find_spec("manim")` and fails fast with an install hint when the package is absent.

Source

Thrown at deeptutor/book/blocks/animation.py:34

from typing import Any

from deeptutor.services.keypool import primary_api_key

from ..models import BlockType, SourceAnchor
from ._prompts import get_book_prompt, load_book_prompts
from .base import BlockContext, BlockGenerator, GenerationFailure

logger = logging.getLogger(__name__)


class AnimationGenerator(BlockGenerator):
    block_type = BlockType.ANIMATION

    async def _generate(
        self, ctx: BlockContext
    ) -> tuple[dict[str, Any], list[SourceAnchor], dict[str, Any]]:
        if importlib.util.find_spec("manim") is None:
            raise GenerationFailure(
                "AnimationGenerator requires the optional math-animator extras. "
                "Install with `pip install -e '.[math-animator]'` "
                "or `pip install -r requirements/math-animator.txt`."
            )

        params = ctx.block.params
        chapter_title = params.get("chapter_title", ctx.chapter.title)
        chapter_summary = params.get("chapter_summary", ctx.chapter.summary)
        objectives = params.get("objectives") or ctx.chapter.learning_objectives
        focus = str(params.get("focus") or "")
        quality = str(params.get("quality") or "medium")
        style_hint = str(params.get("style_hint") or "")
        prompts = load_book_prompts("animation", ctx.language)

        history_lines: list[str] = []
        if chapter_summary:
            history_lines.append(
                get_book_prompt(prompts, "context_summary")

View on GitHub (pinned to 3e82f13042)

Solutions

Install the extra: `pip install -e '.[math-animator]'` (or `pip install -r requirements/math-animator.txt`)
Or `pip install 'deeptutor[math-animator]'` on a released install
Check availability up front via `app.get_capability_availability('math_animator')` before generating
Drop/disable animation blocks in the book outline if video renders aren't needed

Example fix

# before
pip install deeptutor

# after
pip install -e '.[math-animator]'

Defensive patterns

Strategy: validation

Validate before calling

import importlib.util
if importlib.util.find_spec("manim") is None:
    raise SystemExit("math-animator extras required: pip install -e '.[math-animator]'")

Type guard

def animation_available() -> bool:
    return importlib.util.find_spec("manim") is not None

Try / catch

from deeptutor.book.compiler import GenerationFailure
try:
    await generator._generate(ctx)
except GenerationFailure as e:
    if "math-animator extras" in str(e):
        skip_or_disable_animation_blocks()

Prevention

Install '.[math-animator]' in any environment that renders animation blocks
Gate animation blocks on capability availability before compile
Docker/CI images: bake the extra in once

When it happens

Trigger: Building a book whose outline includes an `animation` block on an environment installed with plain `pip install deeptutor` / `deeptutor-cli` (no manim); CI images that omit the extra; a fresh venv after switching install variants.

Common situations: Docker/CI environments trimmed to the base extras; local dev installs using `pip install -e .` instead of `pip install -e '.[math-animator]'`; deploying the CLI-only package and then authoring content with animation blocks.

Related errors

AI-assisted analysis of HKUDS/DeepTutor@3e82f13042 (2026-08-27). Data as JSON: /api/errors/5122fa2da331262e. Report an issue: GitHub.