Skip to content

fix(visualize): guard against invalid visual_genre crashing generation - #748

Open
wangzitiansky wants to merge 1 commit into
HKUDS:devfrom
wangzitiansky:fix/visual-genre-fallback
Open

fix(visualize): guard against invalid visual_genre crashing generation#748
wangzitiansky wants to merge 1 commit into
HKUDS:devfrom
wangzitiansky:fix/visual-genre-fallback

Conversation

@wangzitiansky

@wangzitiansky wangzitiansky commented Aug 1, 2026

Copy link
Copy Markdown

Description

Problem: Book generation crashes when creating interactive visualization
blocks. The analysis LLM sometimes outputs a visual_genre value outside the
allowed list — for example, "simulation" instead of "interactive":

ValidationError: 1 validation error for VisualizationAnalysis
visual_genre
Input should be '', 'flowchart', 'structural', 'illustrative',
'chart', 'stepper', 'interactive', 'mockup' or 'art'
[type=literal_error, input_value='simulation', input_type=str]

Root cause: The user_template_fixed prompt described visual_genre with
an open-ended phrase ("the genre that best fits..."), so the LLM never saw a
hard boundary on which values are actually allowed. Pydantic's
model_validate then raised a ValidationError with no recovery path,
hard-failing the entire pipeline.

Fix: Two-layer defense:

  1. Prompt (prevention): Explicitly enumerate all 8 valid values in
    user_template_fixed (en + zh) so the LLM knows the boundary before
    generating.
  2. Code (fallback): Wrap model_validate with try/except in
    AnalysisAgent — on failure, degrade visual_genre to "" and retry.
    The code generator already has an "any other genre" catch-all branch,
    so empty string degrades gracefully instead of crashing.

Related Issues

  • Closes #...
  • Related to #...

Module(s) Affected

  • agents
  • api
  • config
  • core
  • knowledge
  • logging
  • services
  • tools
  • utils
  • web (Frontend)
  • docs (Documentation)
  • scripts
  • tests
  • Other: ...

Checklist

  • I have read and followed the contribution guidelines.
  • My code follows the project's coding standards.
  • I have run pre-commit run --all-files and fixed any issues.
  • I have added relevant tests for my changes.
  • I have updated the documentation (if necessary).
  • My changes do not introduce any new security vulnerabilities.

Additional Notes

Add any other context or screenshots about the pull request here.

The analysis LLM occasionally outputs visual_genre values outside the
Literal allowlist (e.g. "simulation"), which causes Pydantic's
model_validate to raise ValidationError and hard-fail the entire
book generation pipeline.

Two-layer defense:
- Prompt: enumerate valid values in user_template_fixed (en + zh) so
  the LLM sees a hard boundary before generating.
- Code: wrap model_validate with try/except in AnalysisAgent; on
  failure, degrade visual_genre to "" and retry — graceful fallback
  instead of crashing.

Co-Authored-By: Claude <noreply@anthropic.com>
@wangzitiansky
wangzitiansky force-pushed the fix/visual-genre-fallback branch from 477c0c8 to fb8b849 Compare August 1, 2026 16:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant