HKUDS/DeepTutor · error · ValueError

VisualReviewAgent prompts are not configured.

Error message

VisualReviewAgent prompts are not configured.

What it means

Raised by _extract_docx when python-docx raised while opening the file (primary_error), the OOXML fallback yielded no text, so the original open failure is re-raised wrapped as CorruptDocumentError. Typical cause: the bytes are not a valid DOCX (OOXML) package despite the extension.

Source

Thrown at deeptutor/agents/math_animator/agents/visual_review_agent.py:60

        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,

View on GitHub (pinned to 3e82f13042)

Solutions

1. Convert genuine legacy .doc files with LibreOffice (soffice --convert-to docx) before ingestion
2. Detect OLE2 magic bytes and route to a legacy-format handler
3. Re-save the document from Word to repair structure, then retry

Example fix

// before
text = extract_text_from_bytes(data, filename="old.docx")  # actually OLE2 .doc

// after
subprocess.run(["soffice","--headless","--convert-to","docx","old.doc"], check=True)
text = extract_text_from_bytes(Path("old.docx").read_bytes(), filename="old.docx")

def is_ooxml(data: bytes) -> bool:
    return data[:2] == b"PK"

if not is_ooxml(data):
    route_to_legacy_converter(fn)

except CorruptDocumentError as e:
    if "failed to open DOCX" in str(e):
        convert_with_libreoffice(fn) and retry

When it happens

Trigger: A .doc renamed to .docx (legacy OLE2 format); a truncated or non-zip file with a .docx extension; a Word file with a corrupt contentTypes.xml that python-docx rejects but that contains no recoverable text either.

Common situations: Users renaming old .doc files; partially uploaded files; documents saved by non-conforming generators.

Related errors

• ConceptDesignAgent prompts are not configured.
• math_animator requires optional dependencies. Install with `
• Image mode requires code blocks wrapped in ### YON_IMAGE_n_S
• Model not configured for agent {self.agent_name}. Please act
• The model provider interrupted this response. Please retry.

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