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

Author: gadenbuie

pkg-py/src/querychat/_utils.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import os
+import warnings
 from contextlib import contextmanager
 from typing import TYPE_CHECKING, Optional
 
@@ -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[str]:
+    """
+    Get the tool details setting from environment variable.
+
+    Returns
+    -------
+    Optional[str]
+        The value of QUERYCHAT_TOOL_DETAILS environment variable, or None if not set
+
+    """
+    return os.environ.get("QUERYCHAT_TOOL_DETAILS")
+
+
+def resolve_tool_open_state(action: str, is_error: bool) -> bool:
+    """
+    Determine whether a tool card should be open based on action and setting.
+
+    Parameters
+    ----------
+    action : str
+        The action type ('update', 'query', or 'reset')
+    is_error : bool
+        Whether an error occurred
+
+    Returns
+    -------
+    bool
+        True if the tool card should be open, False otherwise
+
+    """
+    # If there's an error, always show collapsed
+    if is_error:
+        return False
+
+    # Get the tool details setting
+    setting = get_tool_details_setting()
+
+    # If no setting, use default behavior
+    if setting is None:
+        return action != "reset"
+
+    # Validate and apply the setting
+    setting_lower = setting.lower()
+    if setting_lower == "expanded":
+        return True
+    elif setting_lower == "collapsed":
+        return False
+    elif setting_lower == "default":
+        return action != "reset"
+    else:
+        warnings.warn(
+            f"Invalid value for QUERYCHAT_TOOL_DETAILS: {setting!r}. "
+            "Must be one of: 'expanded', 'collapsed', or 'default'",
+            UserWarning,
+            stacklevel=2,
+        )
+        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, resolve_tool_open_state
 
 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=resolve_tool_open_state("update", False),
                     icon=bs_icon("funnel-fill"),
                 ),
             },
@@ -139,7 +139,7 @@ def reset_dashboard() -> ContentToolResult:
                     markdown=button_html,
                     title=None,
                     show_request=False,
-                    open=False,
+                    open=resolve_tool_open_state("reset", False),
                     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=resolve_tool_open_state("query", False),
                     icon=bs_icon("table"),
                 ),
             },

pkg-py/tests/test_tools.py

@@ -0,0 +1,84 @@
+"""Tests for tool functions and utilities."""
+
+import warnings
+
+import pytest
+
+from querychat._utils import resolve_tool_open_state
+
+
+def test_resolve_tool_open_state_default_behavior(monkeypatch):
+    """Test default behavior when no setting is provided."""
+    monkeypatch.delenv("QUERYCHAT_TOOL_DETAILS", raising=False)
+
+    assert resolve_tool_open_state("query", False) is True
+    assert resolve_tool_open_state("update", False) is True
+    assert resolve_tool_open_state("reset", False) is False
+    assert resolve_tool_open_state("query", True) is False
+
+
+def test_resolve_tool_open_state_expanded(monkeypatch):
+    """Test 'expanded' setting."""
+    monkeypatch.setenv("QUERYCHAT_TOOL_DETAILS", "expanded")
+
+    assert resolve_tool_open_state("query", False) is True
+    assert resolve_tool_open_state("update", False) is True
+    assert resolve_tool_open_state("reset", False) is True
+    assert resolve_tool_open_state("query", True) is False
+
+
+def test_resolve_tool_open_state_collapsed(monkeypatch):
+    """Test 'collapsed' setting."""
+    monkeypatch.setenv("QUERYCHAT_TOOL_DETAILS", "collapsed")
+
+    assert resolve_tool_open_state("query", False) is False
+    assert resolve_tool_open_state("update", False) is False
+    assert resolve_tool_open_state("reset", False) is False
+    assert resolve_tool_open_state("query", True) is False
+
+
+def test_resolve_tool_open_state_default_setting(monkeypatch):
+    """Test 'default' setting."""
+    monkeypatch.setenv("QUERYCHAT_TOOL_DETAILS", "default")
+
+    assert resolve_tool_open_state("query", False) is True
+    assert resolve_tool_open_state("update", False) is True
+    assert resolve_tool_open_state("reset", False) is False
+    assert resolve_tool_open_state("query", True) is False
+
+
+def test_resolve_tool_open_state_case_insensitive(monkeypatch):
+    """Test that setting is case-insensitive."""
+    monkeypatch.setenv("QUERYCHAT_TOOL_DETAILS", "EXPANDED")
+    assert resolve_tool_open_state("query", False) is True
+
+    monkeypatch.setenv("QUERYCHAT_TOOL_DETAILS", "Collapsed")
+    assert resolve_tool_open_state("query", False) is False
+
+    monkeypatch.setenv("QUERYCHAT_TOOL_DETAILS", "DeFaUlT")
+    assert resolve_tool_open_state("query", False) is True
+
+
+def test_resolve_tool_open_state_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 = resolve_tool_open_state("query", False)
+
+        assert len(w) == 1
+        assert "Invalid value" in str(w[0].message)
+        assert result is True  # Falls back to default behavior
+
+
+def test_resolve_tool_open_state_error_always_collapsed(monkeypatch):
+    """Test that errors always result in collapsed state."""
+    monkeypatch.setenv("QUERYCHAT_TOOL_DETAILS", "expanded")
+    assert resolve_tool_open_state("query", True) is False
+
+    monkeypatch.setenv("QUERYCHAT_TOOL_DETAILS", "collapsed")
+    assert resolve_tool_open_state("query", True) is False
+
+    monkeypatch.delenv("QUERYCHAT_TOOL_DETAILS", raising=False)
+    assert resolve_tool_open_state("query", True) is False

pkg-r/R/querychat_tools.R

@@ -108,6 +108,37 @@ tool_query <- function(data_source) {
   )
 }
 
+resolve_tool_open_state <- function(action, is_error) {
+  # If there's an error, always show collapsed
+  if (is_error) {
+    return(FALSE)
+  }
+
+  # Get the tool details setting
+  setting <- querychat_tool_details_option()
+
+  # If no setting, use default behavior
+  if (is.null(setting)) {
+    return(action != "reset")
+  }
+
+  # Validate and apply the setting
+  setting <- tolower(setting)
+  switch(
+    setting,
+    "expanded" = TRUE,
+    "collapsed" = FALSE,
+    "default" = action != "reset",
+    {
+      cli::cli_warn(c(
+        "Invalid value for {.code querychat.tool_details} or {.envvar QUERYCHAT_TOOL_DETAILS}: {.val {setting}}",
+        "i" = "Must be one of: {.val expanded}, {.val collapsed}, or {.val default}"
+      ))
+      action != "reset"
+    }
+  )
+}
+
 querychat_tool_result <- function(
   data_source,
   query,
@@ -182,7 +213,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 = resolve_tool_open_state(action, is_error)
       )
     )
   )

pkg-r/R/utils-ellmer.R

@@ -57,3 +57,17 @@ querychat_client_option <- function() {
 
   NULL
 }
+
+querychat_tool_details_option <- function() {
+  opt <- getOption("querychat.tool_details", NULL)
+  if (!is.null(opt)) {
+    return(opt)
+  }
+
+  env <- Sys.getenv("QUERYCHAT_TOOL_DETAILS", "")
+  if (nzchar(env)) {
+    return(env)
+  }
+
+  NULL
+}

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

@@ -0,0 +1,78 @@
+test_that("resolve_tool_open_state respects default behavior", {
+  withr::local_options(querychat.tool_details = NULL)
+  withr::local_envvar(QUERYCHAT_TOOL_DETAILS = NA)
+
+  expect_true(resolve_tool_open_state("query", FALSE))
+  expect_true(resolve_tool_open_state("update", FALSE))
+  expect_false(resolve_tool_open_state("reset", FALSE))
+  expect_false(resolve_tool_open_state("query", TRUE))
+})
+
+test_that("resolve_tool_open_state respects 'expanded' setting via option", {
+  withr::local_options(querychat.tool_details = "expanded")
+
+  expect_true(resolve_tool_open_state("query", FALSE))
+  expect_true(resolve_tool_open_state("update", FALSE))
+  expect_true(resolve_tool_open_state("reset", FALSE))
+  expect_false(resolve_tool_open_state("query", TRUE))
+})
+
+test_that("resolve_tool_open_state respects 'collapsed' setting via option", {
+  withr::local_options(querychat.tool_details = "collapsed")
+
+  expect_false(resolve_tool_open_state("query", FALSE))
+  expect_false(resolve_tool_open_state("update", FALSE))
+  expect_false(resolve_tool_open_state("reset", FALSE))
+  expect_false(resolve_tool_open_state("query", TRUE))
+})
+
+test_that("resolve_tool_open_state respects 'default' setting via option", {
+  withr::local_options(querychat.tool_details = "default")
+
+  expect_true(resolve_tool_open_state("query", FALSE))
+  expect_true(resolve_tool_open_state("update", FALSE))
+  expect_false(resolve_tool_open_state("reset", FALSE))
+  expect_false(resolve_tool_open_state("query", TRUE))
+})
+
+test_that("resolve_tool_open_state respects 'expanded' setting via envvar", {
+  withr::local_options(querychat.tool_details = NULL)
+  withr::local_envvar(QUERYCHAT_TOOL_DETAILS = "expanded")
+
+  expect_true(resolve_tool_open_state("query", FALSE))
+  expect_true(resolve_tool_open_state("update", FALSE))
+  expect_true(resolve_tool_open_state("reset", FALSE))
+})
+
+test_that("resolve_tool_open_state respects 'collapsed' setting via envvar", {
+  withr::local_options(querychat.tool_details = NULL)
+  withr::local_envvar(QUERYCHAT_TOOL_DETAILS = "collapsed")
+
+  expect_false(resolve_tool_open_state("query", FALSE))
+  expect_false(resolve_tool_open_state("update", FALSE))
+  expect_false(resolve_tool_open_state("reset", FALSE))
+})
+
+test_that("resolve_tool_open_state is case-insensitive", {
+  withr::local_options(querychat.tool_details = "EXPANDED")
+  expect_true(resolve_tool_open_state("query", FALSE))
+
+  withr::local_options(querychat.tool_details = "Collapsed")
+  expect_false(resolve_tool_open_state("query", FALSE))
+})
+
+test_that("resolve_tool_open_state warns on invalid setting", {
+  withr::local_options(querychat.tool_details = "invalid")
+
+  expect_warning(
+    resolve_tool_open_state("query", FALSE),
+    "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(resolve_tool_open_state("query", FALSE))
+})