refactor(pkg-py): render charts on demand with ggsql.render_altair()

- Remove chart storage from VisualizeDashboardData and VisualizeQueryData
- Store only viz specs, render charts on demand when needed
- Remove vegalite_to_altair() helper (use ggsql.render_altair() directly)
- Update all framework files (Shiny, Streamlit, Gradio, Dash) to render on demand
- Filter visualizations now always render against current filtered data
- Update tests to reflect new on-demand rendering behavior

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

Author: cpsievert

pkg-py/src/querychat/_dash.py

@@ -98,7 +98,12 @@ def __init__(
         *,
         greeting: Optional[str | PathType] = None,
         client: Optional[str | chatlas.Chat] = None,
-        tools: TOOL_GROUPS | tuple[TOOL_GROUPS, ...] | None = ("update", "query", "visualize_dashboard", "visualize_query"),
+        tools: TOOL_GROUPS | tuple[TOOL_GROUPS, ...] | None = (
+            "update",
+            "query",
+            "visualize_dashboard",
+            "visualize_query",
+        ),
         data_description: Optional[str | PathType] = None,
         categorical_threshold: int = 20,
         extra_instructions: Optional[str | PathType] = None,
@@ -114,7 +119,12 @@ def __init__(
         *,
         greeting: Optional[str | PathType] = None,
         client: Optional[str | chatlas.Chat] = None,
-        tools: TOOL_GROUPS | tuple[TOOL_GROUPS, ...] | None = ("update", "query", "visualize_dashboard", "visualize_query"),
+        tools: TOOL_GROUPS | tuple[TOOL_GROUPS, ...] | None = (
+            "update",
+            "query",
+            "visualize_dashboard",
+            "visualize_query",
+        ),
         data_description: Optional[str | PathType] = None,
         categorical_threshold: int = 20,
         extra_instructions: Optional[str | PathType] = None,
@@ -130,7 +140,12 @@ def __init__(
         *,
         greeting: Optional[str | PathType] = None,
         client: Optional[str | chatlas.Chat] = None,
-        tools: TOOL_GROUPS | tuple[TOOL_GROUPS, ...] | None = ("update", "query", "visualize_dashboard", "visualize_query"),
+        tools: TOOL_GROUPS | tuple[TOOL_GROUPS, ...] | None = (
+            "update",
+            "query",
+            "visualize_dashboard",
+            "visualize_query",
+        ),
         data_description: Optional[str | PathType] = None,
         categorical_threshold: int = 20,
         extra_instructions: Optional[str | PathType] = None,
@@ -146,7 +161,12 @@ def __init__(
         *,
         greeting: Optional[str | PathType] = None,
         client: Optional[str | chatlas.Chat] = None,
-        tools: TOOL_GROUPS | tuple[TOOL_GROUPS, ...] | None = ("update", "query", "visualize_dashboard", "visualize_query"),
+        tools: TOOL_GROUPS | tuple[TOOL_GROUPS, ...] | None = (
+            "update",
+            "query",
+            "visualize_dashboard",
+            "visualize_query",
+        ),
         data_description: Optional[str | PathType] = None,
         categorical_threshold: int = 20,
         extra_instructions: Optional[str | PathType] = None,
@@ -161,7 +181,12 @@ def __init__(
         *,
         greeting: Optional[str | PathType] = None,
         client: Optional[str | chatlas.Chat] = None,
-        tools: TOOL_GROUPS | tuple[TOOL_GROUPS, ...] | None = ("update", "query", "visualize_dashboard", "visualize_query"),
+        tools: TOOL_GROUPS | tuple[TOOL_GROUPS, ...] | None = (
+            "update",
+            "query",
+            "visualize_dashboard",
+            "visualize_query",
+        ),
         data_description: Optional[str | PathType] = None,
         categorical_threshold: int = 20,
         extra_instructions: Optional[str | PathType] = None,
@@ -213,16 +238,23 @@ def ggvis(
             An Altair Chart object, or None if no visualization exists.
 
         """
-        from ._ggsql import vegalite_to_altair
+        import ggsql
 
         if source == "filter":
-            chart_dict = state.get("filter_viz_chart")
+            spec = state.get("filter_viz_spec")
+            if spec is None:
+                return None
+            # Render against current filtered data
+            df = as_narwhals(self.df(state))
+            return ggsql.render_altair(df, spec)
         else:
-            chart_dict = state.get("query_viz_chart")
-
-        if chart_dict is None:
-            return None
-        return vegalite_to_altair(chart_dict)
+            ggsql_query = state.get("query_viz_ggsql")
+            if ggsql_query is None:
+                return None
+            # Re-execute SQL and render
+            sql, viz_spec = ggsql.split_query(ggsql_query)
+            df = as_narwhals(self._data_source.execute_query(sql))
+            return ggsql.render_altair(df, viz_spec)
 
     def ggsql(
         self, state: AppStateDict, source: Literal["filter", "query"] = "filter"
@@ -467,9 +499,7 @@ def app_layout(ids: IDs, table_name: str, chat_ui):
                 srcDoc="<p>No filter visualization yet. Ask the assistant to create one.</p>",
                 style={"width": "100%", "height": "400px", "border": "none"},
             ),
-            dcc.Markdown(
-                id=ids.filter_ggsql, className="querychat-ggsql-display mt-2"
-            ),
+            dcc.Markdown(id=ids.filter_ggsql, className="querychat-ggsql-display mt-2"),
         ],
         title_id=ids.filter_plot_title,
         class_name="h-100",
@@ -483,9 +513,7 @@ def app_layout(ids: IDs, table_name: str, chat_ui):
                 srcDoc="<p>No query visualization yet. Ask the assistant to create one.</p>",
                 style={"width": "100%", "height": "400px", "border": "none"},
             ),
-            dcc.Markdown(
-                id=ids.query_ggsql, className="querychat-ggsql-display mt-2"
-            ),
+            dcc.Markdown(id=ids.query_ggsql, className="querychat-ggsql-display mt-2"),
         ],
         title_id=ids.query_plot_title,
         class_name="h-100",
@@ -545,12 +573,13 @@ def register_app_callbacks(
     deserialize_state: Callable[[AppStateDict], AppState],
 ) -> None:
     """Register callbacks for SQL display, data table, visualizations, and export."""
+    import ggsql
     from dash.dcc.express import send_data_frame
 
     import dash
     from dash import Input, Output, State
 
-    from ._ggsql import vegalite_to_altair
+    from ._ggsql import vegalite_to_html
 
     @app.callback(
         [
@@ -585,7 +614,8 @@ def update_display(state_data: AppStateDict, reset_clicks):
         sql_title = state.title or "SQL Query"
         sql_code = f"```sql\n{state.get_display_sql()}\n```"
 
-        nw_df = as_narwhals(state.get_current_data())
+        current_data = state.get_current_data()
+        nw_df = as_narwhals(current_data)
         nrow, ncol = nw_df.shape
 
         display_df = nw_df.to_pandas()
@@ -598,35 +628,37 @@ def update_display(state_data: AppStateDict, reset_clicks):
         data_info_parts.append(f"Data has {nrow} rows and {ncol} columns.")
         data_info = " ".join(data_info_parts)
 
-        # Filter visualization
+        # Filter visualization - render on demand
         filter_title = state.filter_viz_title or "Filter Plot"
-        filter_chart_dict = state.filter_viz_chart
         filter_spec = state.filter_viz_spec
 
-        if filter_chart_dict:
-            chart = vegalite_to_altair(filter_chart_dict)
-            filter_html = chart.to_html()
+        if filter_spec:
+            # Render against current filtered data
+            chart = ggsql.render_altair(nw_df, filter_spec)
+            filter_html = vegalite_to_html(chart.to_dict())
         else:
             filter_html = (
                 "<p>No filter visualization yet. Ask the assistant to create one.</p>"
             )
 
         filter_ggsql_md = f"```sql\n{filter_spec}\n```" if filter_spec else ""
 
-        # Query visualization
+        # Query visualization - render on demand
         query_title = state.query_viz_title or "Query Plot"
-        query_chart_dict = state.query_viz_chart
-        query_spec = state.query_viz_ggsql
-
-        if query_chart_dict:
-            chart = vegalite_to_altair(query_chart_dict)
-            query_html = chart.to_html()
+        query_ggsql_str = state.query_viz_ggsql
+
+        if query_ggsql_str:
+            # Re-execute SQL and render
+            sql_part, viz_spec = ggsql.split_query(query_ggsql_str)
+            query_df = as_narwhals(state.data_source.execute_query(sql_part))
+            chart = ggsql.render_altair(query_df, viz_spec)
+            query_html = vegalite_to_html(chart.to_dict())
         else:
             query_html = (
                 "<p>No query visualization yet. Ask the assistant to create one.</p>"
             )
 
-        query_ggsql_md = f"```sql\n{query_spec}\n```" if query_spec else ""
+        query_ggsql_md = f"```sql\n{query_ggsql_str}\n```" if query_ggsql_str else ""
 
         return (
             sql_title,

pkg-py/src/querychat/_datasource.py

@@ -206,6 +206,7 @@ def __init__(self, df: nw.DataFrame, table_name: str):
         self._df_lib = native_namespace.__name__
 
         self._conn = duckdb.connect(database=":memory:")
+        # NOTE: if native representation is polars, pyarrow is required for registration
         self._conn.register(table_name, self._df.to_native())
         self._conn.execute("""
 -- extensions: lock down supply chain + auto behaviors

pkg-py/src/querychat/_ggsql.py

@@ -3,66 +3,6 @@
 from __future__ import annotations
 
 import re
-from typing import TYPE_CHECKING, Any
-
-import ggsql._ggsql as ggsql_core
-
-if TYPE_CHECKING:
-    import altair as alt
-
-
-def split_ggsql_query(query: str) -> tuple[str, str]:
-    """
-    Split a ggsql query into SQL and VISUALISE parts.
-
-    Parameters
-    ----------
-    query
-        The full ggsql query string.
-
-    Returns
-    -------
-    tuple[str, str]
-        A tuple of (sql_part, viz_part). If no VISUALISE clause,
-        viz_part will be an empty string.
-
-    """
-    return ggsql_core.split_query(query)
-
-
-def render_visualization(df: Any, viz_spec: str) -> dict[str, Any]:
-    """
-    Render a visualization spec against a DataFrame.
-
-    Parameters
-    ----------
-    df
-        The data to visualize. Can be pandas, polars, or any narwhals-compatible frame.
-    viz_spec
-        The VISUALISE portion of a ggsql query.
-
-    Returns
-    -------
-    dict
-        A Vega-Lite specification as a dictionary.
-
-    """
-    import json
-
-    import narwhals.stable.v1 as nw
-    import polars as pl
-
-    # Convert input to narwhals, then back to native
-    nw_df = nw.from_native(df)
-    native_df = nw_df.to_native()
-
-    # ggsql requires polars DataFrames
-    if not isinstance(native_df, pl.DataFrame):
-        native_df = pl.from_pandas(native_df)
-
-    # Render via ggsql
-    vegalite_json = ggsql_core.render(native_df, viz_spec)
-    return json.loads(vegalite_json)
 
 
 def extract_title(viz_spec: str) -> str | None:
@@ -88,9 +28,11 @@ def extract_title(viz_spec: str) -> str | None:
     return None
 
 
-def vegalite_to_altair(vegalite_spec: dict) -> alt.Chart:
+def vegalite_to_html(vegalite_spec: dict) -> str:
     """
-    Convert a Vega-Lite specification to an Altair Chart.
+    Convert a Vega-Lite specification to standalone HTML.
+
+    This renders the spec directly using vega-embed.
 
     Parameters
     ----------
@@ -99,10 +41,34 @@ def vegalite_to_altair(vegalite_spec: dict) -> alt.Chart:
 
     Returns
     -------
-    alt.Chart
-        An Altair chart object.
+    str
+        A complete HTML document that renders the chart.
 
     """
-    import altair as alt
+    import json
 
-    return alt.Chart.from_dict(vegalite_spec)
+    spec_json = json.dumps(vegalite_spec)
+
+    # ggsql produces v6 specs
+    vl_version = "6"
+
+    return f"""<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="UTF-8">
+  <script src="https://cdn.jsdelivr.net/npm/vega@5"></script>
+  <script src="https://cdn.jsdelivr.net/npm/vega-lite@{vl_version}"></script>
+  <script src="https://cdn.jsdelivr.net/npm/vega-embed@6"></script>
+  <style>
+    body {{ margin: 0; padding: 8px; }}
+    #vis {{ width: 100%; }}
+  </style>
+</head>
+<body>
+  <div id="vis"></div>
+  <script>
+    vegaEmbed('#vis', {spec_json}, {{actions: false}})
+      .catch(console.error);
+  </script>
+</body>
+</html>"""