feat(visualize): replace free-form HTML generation with standardized JSON widget spec framework#488
Open
sagnikonly wants to merge 1 commit into
Open
Conversation
…yle design - Introduced build_widget_from_spec() in utils.py: a fixed Python HTML shell that guarantees consistent 3-zone layout (metric strip → diagram → controls) regardless of which LLM generates the content. LLM now outputs a structured JSON spec (metrics, canvas_html, controls, update_js) instead of raw HTML. - CodeGeneratorAgent: detects JSON widget spec and routes through the fixed shell; falls back to raw HTML for resilience. - VisualizationViewer.tsx: fixed iframe to be fully transparent (allowtransparency, background:transparent) so the widget inherits the app's background. - iframe-html.ts: dark mode injection now uses transparent backgrounds, overrides LLM-injected inline white backgrounds and black text. - Prompts (EN/ZH code_generator_agent + answer_now): updated to request JSON widget spec. Explicit bans on titles, step-by-step solutions inside widget. - Widget shell CSS uses CSS custom properties with @media (prefers-color-scheme) for full light/dark mode support — all colors adapt automatically.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
This PR introduces a standardized widget framework for the
visualizecapability, replacing free-form LLM-generated HTML with a structured, template-driven architecture that guarantees consistent, high-quality interactive widgets regardless of which LLM is used.Problem: The previous approach asked LLMs to generate a complete HTML document for every visualization. This caused layout inconsistency across models, dark mode breakage (hardcoded white backgrounds), LLM reasoning text leaking into the rendered widget, and content overflowing the iframe height.
Solution: The LLM now outputs a structured JSON widget spec (metrics, SVG/canvas, controls, JS update function). A fixed Python shell
build_widget_from_spec()inutils.pyassembles this into a guaranteed 3-zone layout — Metric Strip → Diagram Canvas → Controls — with a full CSS design system that cannot drift with LLM output. The iframe is made transparent so widgets inherit the app's background, and@media (prefers-color-scheme)tokens ensure automatic light/dark adaptation. A graceful HTML fallback is preserved for resilience.Related Issues
Module(s) Affected
agentsapiconfigcoreknowledgeloggingservicestoolsutilsweb(Frontend)docs(Documentation)scriptstests...Checklist
pre-commit run --all-filesand fixed any issues.Additional Notes
Files changed (8 files, 865 insertions, 114 deletions):
deeptutor/agents/visualize/utils.py— Addedbuild_widget_from_spec()fixed shell +is_widget_spec()detectiondeeptutor/agents/visualize/agents/code_generator_agent.py— JSON spec routing with HTML fallbackdeeptutor/agents/visualize/prompts/en|zh/code_generator_agent.yaml— Spec-first prompt with strict output schemadeeptutor/agents/visualize/prompts/en|zh/answer_now.yaml— Fast-path updated to request JSON specweb/components/visualize/VisualizationViewer.tsx— Transparent iframe, reasoning leak guardweb/lib/iframe-html.ts— Transparent dark mode injection, inline-style white/black overridesAll 14 pre-commit hooks passed (ruff, ruff-format, prettier, bandit, mypy, detect-secrets, trailing-whitespace, end-of-file-fixer, check-yaml, check-json, check-toml, check-merge-conflicts, check-case-conflict, check-added-large-files).
New Design
Old Design