feat(pkg-py): add ggsql visualization tool

[cpsievert]

Summary

Adds an opt-in visualize 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, shinywidgets, and vl-convert-python.

Example app

from querychat import QueryChat
from querychat.data import titanic

qc = QueryChat(
    titanic(),
    "titanic",
    tools=("query", "visualize"),
)

app = qc.app()

The visualize 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 tool (opt-in via tools=("query", "visualize")): 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.
• Prompt restructuring: System and tool prompts were reorganized into a unified structure. The LLM is guided to favor visualization over redundant table output, and preparatory queries are collapsed. A comprehensive ggsql syntax reference is included for the LLM.
• Viz state is internal only: No public accessor methods or reactive values for viz state — it's managed entirely by the module/app internals.
  • This is somewhat intentional for now given that there will likely be a "second pass" at ggsql support. At that point, Maybe it will become more clear what sort of state accessor methods might be useful beyond "give me the latest chart".
• Documentation: Added a visualization guide (docs/visualize.qmd) with examples and screenshots.