feat(pkg-py): Add ggsql visualization integration

[cpsievert]

Summary

Integrates ggsql with querychat's Shiny integration to enable LLM-generated data visualizations via a new visualize_query tool that extends the existing tool system.

Uses ggsql's two-stage API (reader.execute() → writer.render()) to gain access to the writer-independent Spec object, enabling structured metadata access (row/column counts, VISUALISE clause, etc.) rather than regex-parsing raw strings.

New Features

• visualize_query tool (opt-in): Creates charts from SQL queries with a VISUALISE clause. The LLM writes a full ggsql query (SQL + VISUALISE), which is executed and rendered as an Altair chart.

• Two-stage ggsql pipeline: A hybrid execute_ggsql() helper uses DataSource for SQL execution (preserving database pushdown for SQLAlchemy/ibis backends), then feeds the result into a ggsql.DuckDBReader for VISUALISE processing → Spec → VegaLiteWriter → Altair chart.

• Accessor methods on QueryChatExpress:

  • ggvis() — Returns rendered Altair chart object
  • ggsql() — Returns ggsql specification string
  • ggtitle() — Returns visualization title

• Tabbed UI: Shiny app() displays Data / Query Plot tabs when viz tool is enabled

• System prompt: ggsql syntax reference included when the visualization tool is enabled

Installation

The visualization tool requires the viz extra:

pip install querychat[viz]

This installs ggsql, altair, and shinywidgets as optional dependencies.

Usage

The visualization tool is opt-in via the tools parameter:

from querychat import QueryChat

qc = QueryChat(
    df, "my_data",
    tools=("update", "query", "visualize_query"),
)

The default remains ("update", "query") — no visualization unless explicitly requested.

Key Files

• pkg-py/src/querychat/_ggsql.py — execute_ggsql(), spec_to_altair(), to_polars(), extract_title()
• pkg-py/src/querychat/tools.py — tool_visualize_query implementation
• pkg-py/src/querychat/prompts/tool-visualize-query.md — Tool prompt template
• pkg-py/src/querychat/prompts/prompt.md — System prompt with ggsql syntax section
• pkg-py/src/querychat/_shiny.py — Shiny UI (Query Plot tab, Express accessors)
• pkg-py/src/querychat/_shiny_module.py — Reactive viz state and chart rendering
• pyproject.toml — viz optional extra

Test Coverage

• New test files:
  • test_ggsql.py — execute_ggsql pipeline, spec_to_altair, extract_title, ggsql.validate() tests
  • test_viz_tools.py — Visualization tool unit tests (dependency checks, tool creation, rendering, error handling)
  • test_visualization_tabs.py — Playwright tests for Shiny viz tabs

---

Before Merging

• Test Shiny app with real LLM interactions
• Verify visualizations render correctly
• Update user-facing docs with visualization examples
• Update changelog

🤖 Generated with Claude Code