Promote "filter" as the preferred name for the "update" tool group

pkg-py/CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Improvements
+
+* The `tools` parameter now uses `"filter"` as the preferred name (instead of `"update"`) for the dashboard-filtering tool group. The default is now `("filter", "query")`. The legacy name `"update"` is still accepted everywhere. (#222)
+
 ### New features
 
 * Added a `"visualize"` tool that lets the LLM create inline Altair charts from natural language requests using [ggsql](https://github.com/posit-dev/ggsql) — a SQL extension for declarative data visualization. Include it via `tools=("query", "visualize")` (or alongside `"update"`). Charts render inline in the chat with fullscreen support, a "Show Query" toggle, and Save as PNG/SVG. Install the optional dependencies with `pip install querychat[viz]`. (#219)

pkg-py/src/querychat/_dash.py

@@ -97,7 +97,7 @@ def __init__(
         *,
         greeting: Optional[str | PathType] = None,
         client: Optional[str | chatlas.Chat] = None,
-        tools: TOOL_GROUPS | tuple[TOOL_GROUPS, ...] | None = ("update", "query"),
+        tools: TOOL_GROUPS | tuple[TOOL_GROUPS, ...] | None = ("filter", "query"),
         data_description: Optional[str | PathType] = None,
         categorical_threshold: int = 20,
         extra_instructions: Optional[str | PathType] = None,
@@ -113,7 +113,7 @@ def __init__(
         *,
         greeting: Optional[str | PathType] = None,
         client: Optional[str | chatlas.Chat] = None,
-        tools: TOOL_GROUPS | tuple[TOOL_GROUPS, ...] | None = ("update", "query"),
+        tools: TOOL_GROUPS | tuple[TOOL_GROUPS, ...] | None = ("filter", "query"),
         data_description: Optional[str | PathType] = None,
         categorical_threshold: int = 20,
         extra_instructions: Optional[str | PathType] = None,
@@ -129,7 +129,7 @@ def __init__(
         *,
         greeting: Optional[str | PathType] = None,
         client: Optional[str | chatlas.Chat] = None,
-        tools: TOOL_GROUPS | tuple[TOOL_GROUPS, ...] | None = ("update", "query"),
+        tools: TOOL_GROUPS | tuple[TOOL_GROUPS, ...] | None = ("filter", "query"),
         data_description: Optional[str | PathType] = None,
         categorical_threshold: int = 20,
         extra_instructions: Optional[str | PathType] = None,
@@ -145,7 +145,7 @@ def __init__(
         *,
         greeting: Optional[str | PathType] = None,
         client: Optional[str | chatlas.Chat] = None,
-        tools: TOOL_GROUPS | tuple[TOOL_GROUPS, ...] | None = ("update", "query"),
+        tools: TOOL_GROUPS | tuple[TOOL_GROUPS, ...] | None = ("filter", "query"),
         data_description: Optional[str | PathType] = None,
         categorical_threshold: int = 20,
         extra_instructions: Optional[str | PathType] = None,
@@ -161,7 +161,7 @@ def __init__(
         *,
         greeting: Optional[str | PathType] = None,
         client: Optional[str | chatlas.Chat] = None,
-        tools: TOOL_GROUPS | tuple[TOOL_GROUPS, ...] | None = ("update", "query"),
+        tools: TOOL_GROUPS | tuple[TOOL_GROUPS, ...] | None = ("filter", "query"),
         data_description: Optional[str | PathType] = None,
         categorical_threshold: int = 20,
         extra_instructions: Optional[str | PathType] = None,
@@ -176,7 +176,7 @@ def __init__(
         *,
         greeting: Optional[str | PathType] = None,
         client: Optional[str | chatlas.Chat] = None,
-        tools: TOOL_GROUPS | tuple[TOOL_GROUPS, ...] | None = ("update", "query"),
+        tools: TOOL_GROUPS | tuple[TOOL_GROUPS, ...] | None = ("filter", "query"),
         data_description: Optional[str | PathType] = None,
         categorical_threshold: int = 20,
         extra_instructions: Optional[str | PathType] = None,

pkg-py/src/querychat/_gradio.py

@@ -91,7 +91,7 @@ def __init__(
         *,
         greeting: Optional[str | Path] = None,
         client: Optional[str | chatlas.Chat] = None,
-        tools: TOOL_GROUPS | tuple[TOOL_GROUPS, ...] | None = ("update", "query"),
+        tools: TOOL_GROUPS | tuple[TOOL_GROUPS, ...] | None = ("filter", "query"),
         data_description: Optional[str | Path] = None,
         categorical_threshold: int = 20,
         extra_instructions: Optional[str | Path] = None,
@@ -106,7 +106,7 @@ def __init__(
         *,
         greeting: Optional[str | Path] = None,
         client: Optional[str | chatlas.Chat] = None,
-        tools: TOOL_GROUPS | tuple[TOOL_GROUPS, ...] | None = ("update", "query"),
+        tools: TOOL_GROUPS | tuple[TOOL_GROUPS, ...] | None = ("filter", "query"),
         data_description: Optional[str | Path] = None,
         categorical_threshold: int = 20,
         extra_instructions: Optional[str | Path] = None,
@@ -121,7 +121,7 @@ def __init__(
         *,
         greeting: Optional[str | Path] = None,
         client: Optional[str | chatlas.Chat] = None,
-        tools: TOOL_GROUPS | tuple[TOOL_GROUPS, ...] | None = ("update", "query"),
+        tools: TOOL_GROUPS | tuple[TOOL_GROUPS, ...] | None = ("filter", "query"),
         data_description: Optional[str | Path] = None,
         categorical_threshold: int = 20,
         extra_instructions: Optional[str | Path] = None,
@@ -136,7 +136,7 @@ def __init__(
         *,
         greeting: Optional[str | Path] = None,
         client: Optional[str | chatlas.Chat] = None,
-        tools: TOOL_GROUPS | tuple[TOOL_GROUPS, ...] | None = ("update", "query"),
+        tools: TOOL_GROUPS | tuple[TOOL_GROUPS, ...] | None = ("filter", "query"),
         data_description: Optional[str | Path] = None,
         categorical_threshold: int = 20,
         extra_instructions: Optional[str | Path] = None,
@@ -151,7 +151,7 @@ def __init__(
         *,
         greeting: Optional[str | Path] = None,
         client: Optional[str | chatlas.Chat] = None,
-        tools: TOOL_GROUPS | tuple[TOOL_GROUPS, ...] | None = ("update", "query"),
+        tools: TOOL_GROUPS | tuple[TOOL_GROUPS, ...] | None = ("filter", "query"),
         data_description: Optional[str | Path] = None,
         categorical_threshold: int = 20,
         extra_instructions: Optional[str | Path] = None,
@@ -165,7 +165,7 @@ def __init__(
         *,
         greeting: Optional[str | Path] = None,
         client: Optional[str | chatlas.Chat] = None,
-        tools: TOOL_GROUPS | tuple[TOOL_GROUPS, ...] | None = ("update", "query"),
+        tools: TOOL_GROUPS | tuple[TOOL_GROUPS, ...] | None = ("filter", "query"),
         data_description: Optional[str | Path] = None,
         categorical_threshold: int = 20,
         extra_instructions: Optional[str | Path] = None,

pkg-py/src/querychat/_querychat_base.py

@@ -39,8 +39,8 @@
 
     from ._viz_tools import VisualizeData
 
-TOOL_GROUPS = Literal["update", "query", "visualize"]
-DEFAULT_TOOLS: tuple[TOOL_GROUPS, ...] = ("update", "query")
+TOOL_GROUPS = Literal["filter", "update", "query", "visualize"]
+DEFAULT_TOOLS: tuple[TOOL_GROUPS, ...] = ("filter", "query")
 
 class QueryChatBase(Generic[IntoFrameT]):
     """
@@ -177,8 +177,9 @@ def client(
         Parameters
         ----------
         tools
-            Which tools to include: `"update"`, `"query"`, `"visualize"`,
-            or a combination.
+            Which tools to include: `"filter"`, `"query"`, `"visualize"`,
+            or a combination. The legacy name `"update"` is still accepted
+            as an alias for `"filter"`.
         update_dashboard
             Callback when update_dashboard tool succeeds.
         reset_dashboard
@@ -306,25 +307,25 @@ def create_client(client: str | chatlas.Chat | None) -> chatlas.Chat:
 
 def normalize_tools(
     tools: TOOL_GROUPS | tuple[TOOL_GROUPS, ...] | None | MISSING_TYPE,
-    default: tuple[TOOL_GROUPS, ...] | None,
+    default: tuple[TOOL_GROUPS, ...] | set[str] | None,
     *,
     check_deps: bool = True,
-) -> tuple[TOOL_GROUPS, ...] | None:
+) -> set[str] | None:
     if tools is None or tools == ():
-        result = None
+        resolved = None
     elif isinstance(tools, MISSING_TYPE):
-        result = default
+        resolved = set(default) if default is not None else None
     elif isinstance(tools, str):
-        result = (tools,)
-    elif isinstance(tools, tuple):
-        result = tools
+        resolved = {tools}
     else:
-        result = tuple(tools)
+        resolved = set(tools)
+    if resolved is not None:
+        resolved = {"update" if t == "filter" else t for t in resolved}
     if not check_deps:
-        return result
-    if has_viz_tool(result) and not has_viz_deps():
+        return resolved
+    if has_viz_tool(resolved) and not has_viz_deps():
         raise ImportError(
             "Visualization tools require ggsql, altair, shinywidgets, and "
             "vl-convert-python. Install them with: pip install querychat[viz]"
         )
-    return result
+    return resolved

pkg-py/src/querychat/_shiny.py

@@ -62,7 +62,7 @@ class QueryChat(QueryChatBase[IntoFrameT]):
     **Privacy-focused mode:** Only allow dashboard filtering, ensuring the LLM
     can't see any raw data.
     ```python
-    qc = QueryChat(df, "my_data", tools="update")
+    qc = QueryChat(df, "my_data", tools="filter")
     qc.app()
     ```
 
@@ -97,15 +97,18 @@ class QueryChat(QueryChatBase[IntoFrameT]):
         defaults to `"openai"`.
     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")`
+        - A single tool string: `"filter"` or `"query"`
+        - A tuple of tools: `("filter", "query", "visualize")`
         - `None` or `()` to disable all tools
 
-        Default is `("update", "query")`. The visualization tool (`"visualize"`)
+        Default is `("filter", "query")`. The visualization tool (`"visualize"`)
         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.
+        Pass only `"filter"` to restrict the LLM to dashboard filtering,
+        omitting both the `"query"` and `"visualize"` tools so the LLM
+        cannot access or display any raw data values.
+
+        The legacy name `"update"` is still accepted as an alias for `"filter"`.
 
         The tools can be overridden per-client by passing a different `tools`
         parameter to the `.client()` method.
@@ -142,7 +145,7 @@ def __init__(
         id: Optional[str] = None,
         greeting: Optional[str | Path] = None,
         client: Optional[str | chatlas.Chat] = None,
-        tools: TOOL_GROUPS | tuple[TOOL_GROUPS, ...] | None = ("update", "query"),
+        tools: TOOL_GROUPS | tuple[TOOL_GROUPS, ...] | None = ("filter", "query"),
         data_description: Optional[str | Path] = None,
         categorical_threshold: int = 20,
         extra_instructions: Optional[str | Path] = None,
@@ -620,7 +623,7 @@ def __init__(
         id: Optional[str] = None,
         greeting: Optional[str | Path] = None,
         client: Optional[str | chatlas.Chat] = None,
-        tools: TOOL_GROUPS | tuple[TOOL_GROUPS, ...] | None = ("update", "query"),
+        tools: TOOL_GROUPS | tuple[TOOL_GROUPS, ...] | None = ("filter", "query"),
         data_description: Optional[str | Path] = None,
         categorical_threshold: int = 20,
         extra_instructions: Optional[str | Path] = None,

pkg-py/src/querychat/_shiny_module.py

@@ -24,7 +24,6 @@
     from shiny import Inputs, Outputs, Session
 
     from ._datasource import DataSource
-    from ._querychat_base import TOOL_GROUPS
     from ._viz_tools import VisualizeData
     from .types import UpdateDashboardData
 
@@ -123,7 +122,7 @@ def mod_server(
     greeting: str | None,
     client: Callable[..., chatlas.Chat],
     enable_bookmarking: bool,
-    tools: tuple[TOOL_GROUPS, ...] | None = None,
+    tools: set[str] | None = None,
 ) -> ServerValues[IntoFrameT]:
     # Reactive values to store state
     sql = ReactiveStringOrNone(None)

pkg-py/src/querychat/_streamlit.py

@@ -66,7 +66,7 @@ def __init__(
         *,
         greeting: Optional[str | Path] = None,
         client: Optional[str | chatlas.Chat] = None,
-        tools: TOOL_GROUPS | tuple[TOOL_GROUPS, ...] | None = ("update", "query"),
+        tools: TOOL_GROUPS | tuple[TOOL_GROUPS, ...] | None = ("filter", "query"),
         data_description: Optional[str | Path] = None,
         categorical_threshold: int = 20,
         extra_instructions: Optional[str | Path] = None,
@@ -81,7 +81,7 @@ def __init__(
         *,
         greeting: Optional[str | Path] = None,
         client: Optional[str | chatlas.Chat] = None,
-        tools: TOOL_GROUPS | tuple[TOOL_GROUPS, ...] | None = ("update", "query"),
+        tools: TOOL_GROUPS | tuple[TOOL_GROUPS, ...] | None = ("filter", "query"),
         data_description: Optional[str | Path] = None,
         categorical_threshold: int = 20,
         extra_instructions: Optional[str | Path] = None,
@@ -96,7 +96,7 @@ def __init__(
         *,
         greeting: Optional[str | Path] = None,
         client: Optional[str | chatlas.Chat] = None,
-        tools: TOOL_GROUPS | tuple[TOOL_GROUPS, ...] | None = ("update", "query"),
+        tools: TOOL_GROUPS | tuple[TOOL_GROUPS, ...] | None = ("filter", "query"),
         data_description: Optional[str | Path] = None,
         categorical_threshold: int = 20,
         extra_instructions: Optional[str | Path] = None,
@@ -111,7 +111,7 @@ def __init__(
         *,
         greeting: Optional[str | Path] = None,
         client: Optional[str | chatlas.Chat] = None,
-        tools: TOOL_GROUPS | tuple[TOOL_GROUPS, ...] | None = ("update", "query"),
+        tools: TOOL_GROUPS | tuple[TOOL_GROUPS, ...] | None = ("filter", "query"),
         data_description: Optional[str | Path] = None,
         categorical_threshold: int = 20,
         extra_instructions: Optional[str | Path] = None,
@@ -126,7 +126,7 @@ def __init__(
         *,
         greeting: Optional[str | Path] = None,
         client: Optional[str | chatlas.Chat] = None,
-        tools: TOOL_GROUPS | tuple[TOOL_GROUPS, ...] | None = ("update", "query"),
+        tools: TOOL_GROUPS | tuple[TOOL_GROUPS, ...] | None = ("filter", "query"),
         data_description: Optional[str | Path] = None,
         categorical_threshold: int = 20,
         extra_instructions: Optional[str | Path] = None,
@@ -140,7 +140,7 @@ def __init__(
         *,
         greeting: Optional[str | Path] = None,
         client: Optional[str | chatlas.Chat] = None,
-        tools: TOOL_GROUPS | tuple[TOOL_GROUPS, ...] | None = ("update", "query"),
+        tools: TOOL_GROUPS | tuple[TOOL_GROUPS, ...] | None = ("filter", "query"),
         data_description: Optional[str | Path] = None,
         categorical_threshold: int = 20,
         extra_instructions: Optional[str | Path] = None,

pkg-py/src/querychat/_system_prompt.py

@@ -12,7 +12,6 @@
 
 if TYPE_CHECKING:
     from ._datasource import DataSource
-    from ._querychat_base import TOOL_GROUPS
 
 
 class QueryChatSystemPrompt:
@@ -62,12 +61,12 @@ def __init__(
         self.categorical_threshold = categorical_threshold
         self.data_source = data_source
 
-    def render(self, tools: tuple[TOOL_GROUPS, ...] | None) -> str:
+    def render(self, tools: set[str] | None) -> str:
         """
         Render system prompt with tool configuration.
 
         Args:
-            tools: Normalized tuple of tool groups to enable (already normalized by caller)
+            tools: Normalized set of tool groups to enable (already normalized by caller)
 
         Returns:
             Fully rendered system prompt string

pkg-py/src/querychat/_viz_utils.py

@@ -9,7 +9,7 @@
 from .__version import __version__
 
 
-def has_viz_tool(tools: tuple[str, ...] | None) -> bool:
+def has_viz_tool(tools: set[str] | None) -> bool:
     """Check if visualize is among the configured tools."""
     return tools is not None and "visualize" in tools
 

pkg-py/tests/playwright/test_10_viz_inline.py

@@ -158,17 +158,3 @@ def test_fullscreen_footer_does_not_stretch(self) -> None:
         assert footer_box is not None
         assert footer_box["height"] < 100
 
-    def test_non_viz_tool_results_have_no_fullscreen(self) -> None:
-        """VIZ-NO-FS: Non-visualization tool results don't have fullscreen."""
-        self.chat.set_user_input("Show me passengers who survived")
-        self.chat.send_user_input(method="click")
-
-        # Wait for a tool result (any)
-        tool_result = self.page.locator(".shiny-tool-result").first
-        expect(tool_result).to_be_visible(timeout=90000)
-
-        # Non-viz tool results should NOT have fullscreen toggle
-        fs_results = self.page.locator(
-            ".shiny-tool-result:has(.tool-fullscreen-toggle)"
-        )
-        expect(fs_results).to_have_count(0)