feat: add option to control tool detail card collapsed/expanded state (#137)

* feat: add option to control tool detail card collapsed/expanded state

Adds support for controlling whether tool detail cards (SQL query and
results) are shown expanded or collapsed by default.

**R package:**
- Option: `querychat.tool_details`
- Environment variable: `QUERYCHAT_TOOL_DETAILS`

**Python package:**
- Environment variable: `QUERYCHAT_TOOL_DETAILS`

**Valid values:**
- `"expanded"` - Tool cards are always shown expanded
- `"collapsed"` - Tool cards are always shown collapsed
- `"default"` - Uses tool-specific behavior (some expanded, some
  collapsed based on tool type)

**Usage:**

```r
# Set for the session
options(querychat.tool_details = "collapsed")

# Or set via environment variable in .Renviron
QUERYCHAT_TOOL_DETAILS=collapsed
```

The option takes precedence over the environment variable in R.

Closes #120

* refactor: simplify tool open state logic

Remove special handling for error states. The tool details setting
now applies uniformly regardless of whether an error occurred.

This simplifies the implementation and gives users full control
over the display state in all cases.

* chore: py-format

* refactor: rename resolve_tool_open_state to querychat_tool_starts_open

Rename function in both R and Python packages for better clarity.
The new name more directly describes what the function returns.

* refactor: move validation logic and reorganize functions

- R: Move querychat_tool_details_option() to querychat_tools.R adjacent to querychat_tool_starts_open()
- R: Move validation logic into querychat_tool_details_option()
- Python: Move validation logic into get_tool_details_setting()
- Simplify querychat_tool_starts_open() in both packages to just apply validated settings

Addresses review comments in PR #137

* style: remove unnecessary comments from new functions

Remove self-explanatory comments that don't add value beyond
what the code clearly expresses.

* chore: small edits

* chore(py): Better typing

Co-authored-by: Carson Sievert <[email protected]>

* docs: add NEWS/CHANGELOG entries for tool details feature

Add entries to R NEWS.md and Python CHANGELOG.md documenting the new
querychat.tool_details option and QUERYCHAT_TOOL_DETAILS environment
variable introduced in PR #137.

* chore(pkg-py): fix types

* chore: fix changelog

* chore: remove changes to duplicate changelog

---------

Co-authored-by: Carson Sievert <[email protected]>

Author: gadenbuie

pkg-py/CHANGELOG.md

@@ -31,6 +31,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 * querychat's system prompt and tool descriptions were rewritten for clarity and future extensibility. (#90)
 
+* Tool detail cards can now be expanded or collapsed by default when querychat runs a query or updates the dashboard via the `QUERYCHAT_TOOL_DETAILS` environment variable. Valid values are `"expanded"`, `"collapsed"`, or `"default"`. (#137)
+
 ## [0.2.2] - 2025-09-04
 
 * Fixed another issue with data sources that aren't already narwhals DataFrames (#83)

pkg-py/src/querychat/_utils.py

@@ -1,8 +1,9 @@
 from __future__ import annotations
 
 import os
+import warnings
 from contextlib import contextmanager
-from typing import TYPE_CHECKING, Optional
+from typing import TYPE_CHECKING, Literal, Optional
 
 import narwhals.stable.v1 as nw
 
@@ -53,6 +54,65 @@ def temp_env_vars(env_vars: dict[str, Optional[str]]):
                 os.environ[key] = original_value
 
 
+def get_tool_details_setting() -> Optional[Literal["expanded", "collapsed", "default"]]:
+    """
+    Get and validate the tool details setting from environment variable.
+
+    Returns
+    -------
+    Optional[str]
+        The validated value of QUERYCHAT_TOOL_DETAILS environment variable
+        (one of 'expanded', 'collapsed', or 'default'), or None if not set
+        or invalid
+
+    """
+    setting = os.environ.get("QUERYCHAT_TOOL_DETAILS")
+    if setting is None:
+        return None
+
+    setting_lower = setting.lower()
+    valid_settings = ("expanded", "collapsed", "default")
+
+    if setting_lower not in valid_settings:
+        warnings.warn(
+            f"Invalid value for QUERYCHAT_TOOL_DETAILS: {setting!r}. "
+            "Must be one of: 'expanded', 'collapsed', or 'default'",
+            UserWarning,
+            stacklevel=2,
+        )
+        return None
+
+    return setting_lower
+
+
+def querychat_tool_starts_open(action: Literal["update", "query", "reset"]) -> bool:
+    """
+    Determine whether a tool card should be open based on action and setting.
+
+    Parameters
+    ----------
+    action : str
+        The action type ('update', 'query', or 'reset')
+
+    Returns
+    -------
+    bool
+        True if the tool card should be open, False otherwise
+
+    """
+    setting = get_tool_details_setting()
+
+    if setting is None:
+        return action != "reset"
+
+    if setting == "expanded":
+        return True
+    elif setting == "collapsed":
+        return False
+    else:  # setting == "default"
+        return action != "reset"
+
+
 def df_to_html(df: IntoFrame, maxrows: int = 5) -> str:
     """
     Convert a DataFrame to an HTML table for display in chat.

pkg-py/src/querychat/tools.py

@@ -8,7 +8,7 @@
 from shinychat.types import ToolResultDisplay
 
 from ._icons import bs_icon
-from ._utils import df_to_html
+from ._utils import df_to_html, querychat_tool_starts_open
 
 if TYPE_CHECKING:
     from ._datasource import DataSource
@@ -65,7 +65,7 @@ def update_dashboard(query: str, title: str) -> ContentToolResult:
                     markdown=markdown + f"\n\n{button_html}",
                     title=title,
                     show_request=False,
-                    open=True,
+                    open=querychat_tool_starts_open("update"),
                     icon=bs_icon("funnel-fill"),
                 ),
             },
@@ -139,7 +139,7 @@ def reset_dashboard() -> ContentToolResult:
                     markdown=button_html,
                     title=None,
                     show_request=False,
-                    open=False,
+                    open=querychat_tool_starts_open("reset"),
                     icon=bs_icon("arrow-counterclockwise"),
                 ),
             },
@@ -208,7 +208,7 @@ def query(query: str, _intent: str = "") -> ContentToolResult:
                 "display": ToolResultDisplay(
                     markdown=markdown,
                     show_request=False,
-                    open=True,
+                    open=querychat_tool_starts_open("query"),
                     icon=bs_icon("table"),
                 ),
             },

pkg-py/tests/test_tools.py

@@ -0,0 +1,66 @@
+"""Tests for tool functions and utilities."""
+
+import warnings
+
+from querychat._utils import querychat_tool_starts_open
+
+
+def test_querychat_tool_starts_open_default_behavior(monkeypatch):
+    """Test default behavior when no setting is provided."""
+    monkeypatch.delenv("QUERYCHAT_TOOL_DETAILS", raising=False)
+
+    assert querychat_tool_starts_open("query") is True
+    assert querychat_tool_starts_open("update") is True
+    assert querychat_tool_starts_open("reset") is False
+
+
+def test_querychat_tool_starts_open_expanded(monkeypatch):
+    """Test 'expanded' setting."""
+    monkeypatch.setenv("QUERYCHAT_TOOL_DETAILS", "expanded")
+
+    assert querychat_tool_starts_open("query") is True
+    assert querychat_tool_starts_open("update") is True
+    assert querychat_tool_starts_open("reset") is True
+
+
+def test_querychat_tool_starts_open_collapsed(monkeypatch):
+    """Test 'collapsed' setting."""
+    monkeypatch.setenv("QUERYCHAT_TOOL_DETAILS", "collapsed")
+
+    assert querychat_tool_starts_open("query") is False
+    assert querychat_tool_starts_open("update") is False
+    assert querychat_tool_starts_open("reset") is False
+
+
+def test_querychat_tool_starts_open_default_setting(monkeypatch):
+    """Test 'default' setting."""
+    monkeypatch.setenv("QUERYCHAT_TOOL_DETAILS", "default")
+
+    assert querychat_tool_starts_open("query") is True
+    assert querychat_tool_starts_open("update") is True
+    assert querychat_tool_starts_open("reset") is False
+
+
+def test_querychat_tool_starts_open_case_insensitive(monkeypatch):
+    """Test that setting is case-insensitive."""
+    monkeypatch.setenv("QUERYCHAT_TOOL_DETAILS", "EXPANDED")
+    assert querychat_tool_starts_open("query") is True
+
+    monkeypatch.setenv("QUERYCHAT_TOOL_DETAILS", "Collapsed")
+    assert querychat_tool_starts_open("query") is False
+
+    monkeypatch.setenv("QUERYCHAT_TOOL_DETAILS", "DeFaUlT")
+    assert querychat_tool_starts_open("query") is True
+
+
+def test_querychat_tool_starts_open_invalid_setting(monkeypatch):
+    """Test warning on invalid setting."""
+    monkeypatch.setenv("QUERYCHAT_TOOL_DETAILS", "invalid")
+
+    with warnings.catch_warnings(record=True) as w:
+        warnings.simplefilter("always")
+        result = querychat_tool_starts_open("query")
+
+        assert len(w) == 1
+        assert "Invalid value" in str(w[0].message)
+        assert result is True  # Falls back to default behavior

pkg-r/NEWS.md

@@ -1,5 +1,7 @@
 # querychat (development version)
 
+* Tool detail cards can now be expanded or collapsed by default when querychat runs a query or updates the dashboard via the `querychat.tool_details` R option or the `QUERYCHAT_TOOL_DETAILS` environment variable. Valid values are `"expanded"`, `"collapsed"`, or `"default"`. (#137)
+
 * Added bookmarking support to `QueryChat$server()` and `querychat_app()`. When bookmarking is enabled (via `bookmark_store = "url"` or `"server"` in `querychat_app()` or `$app_obj()`, or via `enable_bookmarking = TRUE` in `$server()`), the chat state (including current query, title, and chat history) will be saved and restored with Shiny bookmarks. (#107)
 
 * Nearly the entire functional API (i.e., `querychat_init()`, `querychat_sidebar()`, `querychat_server()`, etc) has been hard deprecated in favor of a simpler OOP-based API. Namely, the new `QueryChat$new()` class is now the main entry point (instead of `querychat_init()`) and has methods to replace old functions (e.g., `$sidebar()`, `$server()`, etc). (#109)

pkg-r/R/querychat_tools.R

@@ -108,6 +108,48 @@ tool_query <- function(data_source) {
   )
 }
 
+querychat_tool_details_option <- function() {
+  opt <- getOption("querychat.tool_details", NULL)
+  if (!is.null(opt)) {
+    setting <- opt
+  } else {
+    env <- Sys.getenv("QUERYCHAT_TOOL_DETAILS", "")
+    if (nzchar(env)) {
+      setting <- env
+    } else {
+      return(NULL)
+    }
+  }
+
+  setting <- tolower(setting)
+  valid_settings <- c("expanded", "collapsed", "default")
+
+  if (!setting %in% valid_settings) {
+    cli::cli_warn(c(
+      "Invalid value for {.code querychat.tool_details} or {.envvar QUERYCHAT_TOOL_DETAILS}: {.val {setting}}",
+      "i" = "Must be one of: {.or {.val {valid_settings}}}"
+    ))
+    return(NULL)
+  }
+
+  setting
+}
+
+querychat_tool_starts_open <- function(action) {
+  setting <- querychat_tool_details_option()
+
+  if (is.null(setting)) {
+    return(action != "reset")
+  }
+
+  switch(
+    setting,
+    "expanded" = TRUE,
+    "collapsed" = FALSE,
+    action != "reset"
+  )
+}
+
 querychat_tool_result <- function(
   data_source,
   query,
@@ -182,7 +224,7 @@ querychat_tool_result <- function(
         title = if (action == "update" && !is.null(title)) title,
         show_request = is_error,
         markdown = display_md,
-        open = !is_error && action != "reset"
+        open = querychat_tool_starts_open(action)
       )
     )
   )

pkg-r/tests/testthat/test-querychat_tools.R

@@ -0,0 +1,74 @@
+test_that("querychat_tool_starts_open respects default behavior", {
+  withr::local_options(querychat.tool_details = NULL)
+  withr::local_envvar(QUERYCHAT_TOOL_DETAILS = NA)
+
+  expect_true(querychat_tool_starts_open("query"))
+  expect_true(querychat_tool_starts_open("update"))
+  expect_false(querychat_tool_starts_open("reset"))
+})
+
+test_that("querychat_tool_starts_open respects 'expanded' setting via option", {
+  withr::local_options(querychat.tool_details = "expanded")
+
+  expect_true(querychat_tool_starts_open("query"))
+  expect_true(querychat_tool_starts_open("update"))
+  expect_true(querychat_tool_starts_open("reset"))
+})
+
+test_that("querychat_tool_starts_open respects 'collapsed' setting via option", {
+  withr::local_options(querychat.tool_details = "collapsed")
+
+  expect_false(querychat_tool_starts_open("query"))
+  expect_false(querychat_tool_starts_open("update"))
+  expect_false(querychat_tool_starts_open("reset"))
+})
+
+test_that("querychat_tool_starts_open respects 'default' setting via option", {
+  withr::local_options(querychat.tool_details = "default")
+
+  expect_true(querychat_tool_starts_open("query"))
+  expect_true(querychat_tool_starts_open("update"))
+  expect_false(querychat_tool_starts_open("reset"))
+})
+
+test_that("querychat_tool_starts_open respects 'expanded' setting via envvar", {
+  withr::local_options(querychat.tool_details = NULL)
+  withr::local_envvar(QUERYCHAT_TOOL_DETAILS = "expanded")
+
+  expect_true(querychat_tool_starts_open("query"))
+  expect_true(querychat_tool_starts_open("update"))
+  expect_true(querychat_tool_starts_open("reset"))
+})
+
+test_that("querychat_tool_starts_open respects 'collapsed' setting via envvar", {
+  withr::local_options(querychat.tool_details = NULL)
+  withr::local_envvar(QUERYCHAT_TOOL_DETAILS = "collapsed")
+
+  expect_false(querychat_tool_starts_open("query"))
+  expect_false(querychat_tool_starts_open("update"))
+  expect_false(querychat_tool_starts_open("reset"))
+})
+
+test_that("querychat_tool_starts_open is case-insensitive", {
+  withr::local_options(querychat.tool_details = "EXPANDED")
+  expect_true(querychat_tool_starts_open("query"))
+
+  withr::local_options(querychat.tool_details = "Collapsed")
+  expect_false(querychat_tool_starts_open("query"))
+})
+
+test_that("querychat_tool_starts_open warns on invalid setting", {
+  withr::local_options(querychat.tool_details = "invalid")
+
+  expect_warning(
+    querychat_tool_starts_open("query"),
+    "Invalid value for"
+  )
+})
+
+test_that("option takes precedence over environment variable", {
+  withr::local_options(querychat.tool_details = "collapsed")
+  withr::local_envvar(QUERYCHAT_TOOL_DETAILS = "expanded")
+
+  expect_false(querychat_tool_starts_open("query"))
+})