refactor: drop visualize_dashboard, switch visualize_query to two-stage ggsql API

Remove the visualize_dashboard tool to focus on visualize_query. Switch
from the one-shot ggsql.render_altair() API to the two-stage API
(reader.execute → writer.render), gaining access to ggsql's writer-
independent Spec object for structured metadata access.

The new execute_ggsql() helper uses a hybrid approach: DataSource handles
SQL execution (preserving database pushdown), then a ggsql DuckDBReader
processes the VISUALISE portion to produce a Spec. Title extraction now
reads from the rendered Vega-Lite JSON rather than regex-parsing the
VISUALISE string.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: cpsievert

pkg-py/src/querychat/__init__.py

@@ -2,11 +2,10 @@
 from ._deprecated import mod_server as server
 from ._deprecated import mod_ui as ui
 from ._shiny import QueryChat
-from .tools import VisualizeDashboardData, VisualizeQueryData
+from .tools import VisualizeQueryData
 
 __all__ = (
     "QueryChat",
-    "VisualizeDashboardData",
     "VisualizeQueryData",
     # TODO(lifecycle): Remove these deprecated functions when we reach v1.0
     "greeting",

pkg-py/src/querychat/_ggsql.py

@@ -1,39 +1,84 @@
-"""
-Helpers for ggsql integration.
-
-These are workarounds for functionality not yet exposed by the ggsql package.
-When ggsql adds native title/metadata extraction, these should be replaced.
-"""
+"""Helpers for ggsql integration."""
 
 from __future__ import annotations
 
-import re
+import json
+from typing import TYPE_CHECKING
+
+import narwhals.stable.v1 as nw
+
+if TYPE_CHECKING:
+    import ggsql
+    import polars as pl
+    from narwhals.stable.v1.typing import IntoFrame
+
+    from ._datasource import DataSource
+
 
+def to_polars(data: IntoFrame) -> pl.DataFrame:
+    """Convert any narwhals-compatible frame to a polars DataFrame."""
+    nw_df = nw.from_native(data)
+    if isinstance(nw_df, nw.LazyFrame):
+        nw_df = nw_df.collect()
+    return nw_df.to_polars()
 
-def extract_title(viz_spec: str) -> str | None:
+
+def execute_ggsql(data_source: DataSource, query: str) -> ggsql.Spec:
     """
-    Extract the title from a VISUALISE spec's LABEL clause.
+    Execute a full ggsql query against a DataSource, returning a Spec.
 
-    .. note::
-        This is a workaround. Ideally ggsql would expose title extraction
-        from its ``Validated`` or ``Spec`` objects. This regex will break if
-        ggsql's LABEL syntax changes (e.g., escaped quotes, multi-line values).
-        TODO: File ggsql issue for native title extraction API.
+    Uses ggsql.validate() to split SQL from VISUALISE, executes the SQL
+    through DataSource (preserving database pushdown), then feeds the result
+    into a ggsql DuckDBReader to produce a Spec.
 
     Parameters
     ----------
-    viz_spec
-        The VISUALISE portion of a ggsql query.
+    data_source
+        The querychat DataSource to execute the SQL portion against.
+    query
+        A full ggsql query (SQL + VISUALISE).
 
     Returns
     -------
-    str | None
-        The title if found, otherwise None.
+    ggsql.Spec
+        The writer-independent plot specification.
 
     """
-    # Match LABEL title => 'value' or LABEL title => "value"
-    pattern = r"LABEL\s+title\s*=>\s*['\"]([^'\"]+)['\"]"
-    match = re.search(pattern, viz_spec, re.IGNORECASE)
-    if match:
-        return match.group(1)
+    import ggsql as _ggsql
+
+    validated = _ggsql.validate(query)
+    pl_df = to_polars(data_source.execute_query(validated.sql()))
+
+    reader = _ggsql.DuckDBReader("duckdb://memory")
+    reader.register("_data", pl_df)
+    return reader.execute(f"SELECT * FROM _data {validated.visual()}")
+
+
+def spec_to_altair(spec: ggsql.Spec) -> ggsql.AltairChart:
+    """Render a ggsql Spec to an Altair chart via VegaLiteWriter."""
+    import ggsql as _ggsql
+
+    writer = _ggsql.VegaLiteWriter()
+    vegalite_json = writer.render(spec)
+
+    import altair as alt
+
+    return alt.Chart.from_json(vegalite_json)
+
+
+def extract_title(spec: ggsql.Spec) -> str | None:
+    """
+    Extract the title from a ggsql Spec's rendered Vega-Lite JSON.
+
+    TODO: Replace with ``spec.title()`` once ggsql exposes this natively.
+    """
+    import ggsql as _ggsql
+
+    writer = _ggsql.VegaLiteWriter()
+    vl: dict[str, object] = json.loads(writer.render(spec))
+    title = vl.get("title")
+    if isinstance(title, str):
+        return title
+    if isinstance(title, dict):
+        return title.get("text")
     return None

pkg-py/src/querychat/_querychat_base.py

@@ -25,12 +25,10 @@
 from ._utils import MISSING, MISSING_TYPE, is_ibis_table
 from .tools import (
     UpdateDashboardData,
-    VisualizeDashboardData,
     VisualizeQueryData,
     tool_query,
     tool_reset_dashboard,
     tool_update_dashboard,
-    tool_visualize_dashboard,
     tool_visualize_query,
 )
 
@@ -39,16 +37,15 @@
 
     from narwhals.stable.v1.typing import IntoFrame
 
-TOOL_GROUPS = Literal["update", "query", "visualize_dashboard", "visualize_query"]
+TOOL_GROUPS = Literal["update", "query", "visualize_query"]
 DEFAULT_TOOLS: tuple[TOOL_GROUPS, ...] = ("update", "query")
 ALL_TOOLS: tuple[TOOL_GROUPS, ...] = (
     "update",
     "query",
-    "visualize_dashboard",
     "visualize_query",
 )
 
-VIZ_TOOLS: tuple[TOOL_GROUPS, ...] = ("visualize_dashboard", "visualize_query")
+VIZ_TOOLS: tuple[TOOL_GROUPS, ...] = ("visualize_query",)
 
 
 def check_viz_dependencies(tools: tuple[TOOL_GROUPS, ...] | None) -> None:
@@ -163,7 +160,6 @@ def client(
         tools: TOOL_GROUPS | tuple[TOOL_GROUPS, ...] | None | MISSING_TYPE = MISSING,
         update_dashboard: Callable[[UpdateDashboardData], None] | None = None,
         reset_dashboard: Callable[[], None] | None = None,
-        visualize_dashboard: Callable[[VisualizeDashboardData], None] | None = None,
         visualize_query: Callable[[VisualizeQueryData], None] | None = None,
     ) -> chatlas.Chat:
         """
@@ -172,14 +168,12 @@ def client(
         Parameters
         ----------
         tools
-            Which tools to include: `"update"`, `"query"`, `"visualize_dashboard"`,
-            `"visualize_query"`, or a combination.
+            Which tools to include: `"update"`, `"query"`, `"visualize_query"`,
+            or a combination.
         update_dashboard
             Callback when update_dashboard tool succeeds.
         reset_dashboard
             Callback when reset_dashboard tool is invoked.
-        visualize_dashboard
-            Callback when visualize_dashboard tool succeeds.
         visualize_query
             Callback when visualize_query tool succeeds.
 
@@ -210,10 +204,6 @@ def client(
         if "query" in tools:
             chat.register_tool(tool_query(data_source))
 
-        if "visualize_dashboard" in tools:
-            viz_fn = visualize_dashboard or (lambda _: None)
-            chat.register_tool(tool_visualize_dashboard(self._data_source, viz_fn))
-
         if "visualize_query" in tools:
             query_viz_fn = visualize_query or (lambda _: None)
             chat.register_tool(tool_visualize_query(self._data_source, query_viz_fn))

pkg-py/src/querychat/_shiny.py

@@ -98,11 +98,11 @@ class QueryChat(QueryChatBase[IntoFrameT]):
     tools
         Which querychat tools to include in the chat client by default. Can be:
         - A single tool string: `"update"` or `"query"`
-        - A tuple of tools: `("update", "query", "visualize_dashboard", "visualize_query")`
+        - A tuple of tools: `("update", "query", "visualize_query")`
         - `None` or `()` to disable all tools
 
-        Default is `("update", "query")`. Visualization tools (`"visualize_dashboard"`,
-        `"visualize_query"`) can be opted into by including them in the tuple.
+        Default is `("update", "query")`. The visualization tool (`"visualize_query"`)
+        can be opted into by including it in the tuple.
 
         Set to `"update"` to prevent the LLM from accessing data values, only
         allowing dashboard filtering without answering questions.
@@ -250,9 +250,8 @@ def app(
         Creates a Shiny app with a chat sidebar and tabbed view -- providing a
         quick-and-easy way to start chatting with your data.
 
-        The app includes three tabs:
+        The app includes two tabs:
         - **Data**: Shows the filtered data table
-        - **Filter Plot**: Shows the persistent dashboard visualization
         - **Query Plot**: Shows the most recent query visualization
 
         Parameters
@@ -278,7 +277,6 @@ def app(
             if isinstance(self.tools, str)
             else (self.tools or ())
         )
-        has_filter_viz = "visualize_dashboard" in tools_tuple
         has_query_viz = "visualize_query" in tools_tuple
 
         def app_ui(request):
@@ -291,13 +289,6 @@ def app_ui(request):
                     ),
                 ),
             ]
-            if has_filter_viz:
-                nav_panels.append(
-                    ui.nav_panel(
-                        "Filter Plot",
-                        ui.output_ui("filter_plot_container"),
-                    )
-                )
             if has_query_viz:
                 nav_panels.append(
                     ui.nav_panel(
@@ -374,37 +365,6 @@ def sql_output():
                     width="100%",
                 )
 
-            if has_filter_viz:
-
-                @render.ui
-                def filter_plot_container():
-                    from shinywidgets import output_widget, render_altair
-
-                    chart = vals.filter_viz_chart()
-                    if chart is None:
-                        return ui.card(
-                            ui.card_body(
-                                ui.p(
-                                    "No filter visualization yet. "
-                                    "Use the chat to create one."
-                                ),
-                                class_="text-muted text-center py-5",
-                            ),
-                        )
-
-                    @render_altair
-                    def filter_chart():
-                        return chart
-
-                    return ui.card(
-                        ui.card_header(
-                            bs_icon("bar-chart-fill"),
-                            " ",
-                            vals.filter_viz_title.get() or "Filter Visualization",
-                        ),
-                        output_widget("filter_chart"),
-                    )
-
             if has_query_viz:
 
                 @render.ui
@@ -971,68 +931,38 @@ def title(self, value: Optional[str] = None) -> str | None | bool:
         else:
             return self._vals.title.set(value)
 
-    def ggvis(self, source: Literal["filter", "query"] = "filter") -> alt.Chart | None:
+    def ggvis(self) -> alt.Chart | None:
         """
-        Get the visualization chart.
-
-        Parameters
-        ----------
-        source
-            Which visualization to return:
-            - "filter": Chart from visualize_dashboard (updates with filter changes)
-            - "query": Chart from visualize_query (most recent inline visualization)
+        Get the visualization chart from the most recent visualize_query call.
 
         Returns
         -------
         :
             The Altair chart, or None if no visualization exists.
 
         """
-        if source == "filter":
-            return self._vals.filter_viz_chart()
-        else:
-            return self._vals.query_viz_chart()
+        return self._vals.query_viz_chart()
 
-    def ggsql(self, source: Literal["filter", "query"] = "filter") -> str | None:
+    def ggsql(self) -> str | None:
         """
-        Get the ggsql specification.
-
-        Parameters
-        ----------
-        source
-            Which specification to return:
-            - "filter": VISUALISE spec only (from visualize_dashboard)
-            - "query": Full ggsql query (from visualize_query)
+        Get the full ggsql query from the most recent visualize_query call.
 
         Returns
         -------
         :
-            The ggsql specification, or None if no visualization exists.
+            The ggsql query string, or None if no visualization exists.
 
         """
-        if source == "filter":
-            return self._vals.filter_viz_spec.get()
-        else:
-            return self._vals.query_viz_ggsql.get()
+        return self._vals.query_viz_ggsql.get()
 
-    def ggtitle(self, source: Literal["filter", "query"] = "filter") -> str | None:
+    def ggtitle(self) -> str | None:
         """
-        Get the visualization title.
-
-        Parameters
-        ----------
-        source
-            Which title to return:
-            - "filter": Title from visualize_dashboard
-            - "query": Title from visualize_query
+        Get the visualization title from the most recent visualize_query call.
 
         Returns
         -------
         :
             The title, or None if no visualization exists.
 
         """
-        if source == "filter":
-            return self._vals.filter_viz_title.get()
-        else:
-            return self._vals.query_viz_title.get()
+        return self._vals.query_viz_title.get()