feat(pkg-py): add ggsql visualization tool

[cpsievert]

Summary

Adds an opt-in visualize_query tool to querychat's Python package, enabling LLM-generated data visualizations via ggsql. When enabled, the LLM can write ggsql queries (SQL + VISUALISE clause) that are executed and rendered as interactive Altair charts inline in the chat.

Usage

Install

pip install querychat[viz]

This installs the optional dependencies: ggsql, altair, and shinywidgets.

Example app

from querychat import QueryChat from querychat.data import titanic qc = QueryChat( titanic(), "titanic", tools=("query", "visualize_query"), ) app = qc.app()

The visualize_query tool is opt-in — include it in the tools tuple alongside "query" and/or "update" to enable it.

What it looks like

Charts render inline in the chat with a collapsible footer showing the ggsql query (with syntax highlighting), a copy button, and save options:

---

Key changes

• visualize_query tool (opt-in via tools=("query", "visualize_query")): The LLM writes a full ggsql query, which is executed against the data source and rendered as an Altair chart.
• Two-stage ggsql pipeline (_viz_ggsql.py): Uses DataSource for SQL execution (preserving database pushdown), then feeds results into ggsql for VISUALISE processing → Altair chart.
• Inline chart rendering (_viz_altair_widget.py): Custom AltairWidget for rendering charts directly in the chat stream, with JS/CSS assets for interactive display.
• ggsql prompt & syntax reference (tool-visualize-query.md): Detailed tool prompt with ggsql syntax guidance, plus filter-awareness instructions added to the query tool prompt.
• Viz state is internal only: No public accessor methods or reactive values for viz state — it's managed entirely by the module/app internals via a private _ServerValues subclass.
• R prompt changes: Minor updates to pkg-r/inst/prompts/prompt.md and tool-query.md for filter-awareness guidance (keeping prompts in sync).

Test coverage

• test_ggsql.py — ggsql execution pipeline, spec-to-Altair conversion, title extraction, validation
• test_viz_tools.py — Tool creation, rendering, error handling
• test_viz_footer.py — Footer HTML structure, icons, JS invariants
• playwright/test_10_viz_inline.py — Inline chart Playwright tests
• playwright/test_11_viz_footer.py — Footer interaction Playwright tests

---

Before Merging

• Add dependency requirements (ggsql latest, shinychat card footer/full-screen, py-shiny ggsql code editor, bslib ggsql code editor)
• Update user-facing docs with visualization examples
• Update changelog

🤖 Generated with Claude Code