HKUDS/DeepTutor · error · ValueError

CodeGeneratorAgent generation prompts are not configured.

Error message

CodeGeneratorAgent generation prompts are not configured.

What it means

Raised by the pypdf fallback branch of _extract_pdf when neither pymupdf nor pypdf could be imported. The module degrades gracefully at import time, so PDF extraction only fails at call time when no reader library exists in the environment.

Source

Thrown at deeptutor/agents/math_animator/agents/code_generator_agent.py:61

            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),
        )
        _chunks: list[str] = []
        async for _c in self.stream_llm(
            user_prompt=user_prompt,
            system_prompt=system_prompt,
            response_format={"type": "json_object"},
            stage="code_generation",

View on GitHub (pinned to 3e82f13042)

Solutions

Install a PDF reader: pip install pymupdf (preferred) or pip install pypdf
If installation conflicts, check pip check / dependency pins that exclude pymupdf and loosen them
Pre-check import fitz or pypdf before offering PDF upload in the UI/API

Example fix

// before
# environment lacks pymupdf and pypdf
text = extract_text_from_bytes(data, filename="doc.pdf")  # raises

// after
pip install pymupdf
text = extract_text_from_bytes(data, filename="doc.pdf")

Defensive patterns

Strategy: validation

Validate before calling

def pdf_reader_available() -> bool:
    try:
        import fitz  # noqa
        return True
    except ImportError:
        pass
    try:
        import pypdf  # noqa
        return True
    except ImportError:
        return False

assert pdf_reader_available(), "install pymupdf or pypdf to ingest PDFs"

Try / catch

try:
    text = extract_text_from_bytes(data, filename=fn)
except CorruptDocumentError as e:
    if "no PDF reader available" in str(e):
        raise RuntimeError("missing dependency: pip install pymupdf") from e

Prevention

Include pymupdf in deployment dependency locks
Run a dependency smoke test at service startup for each ingest format you support

When it happens

Trigger: Running in a minimal install (deeptutor-cli without PDF extras) and calling extract_text_from_bytes on a .pdf; a venv where pymupdf/pypdf were uninstalled or failed to build.

Common situations: Slim Docker images or CI environments that trimmed optional dependencies; pip resolver dropping pymupdf due to a conflicting pin on another package.

Related errors

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