feat: Add querychat_greeting() (#87)

* feat(pkg-r): Add `querychat_greeting()`

* Gives an easy way to generate a greeting once

* feat(pkg-py): Add `querychat_greeting()`

* update docs

* pkg-py: hint about querychat greeting in init()

* ide: hook up testing pane

* add changelog items

* fix docs

* tests: fix test

* r build ignore things

Author: gadenbuie

.vscode/settings.json

@@ -8,5 +8,12 @@
     },
     "editor.defaultFormatter": "charliermarsh.ruff",
   },
-  "flake8.args": ["--max-line-length=120"]
+  "flake8.args": [
+    "--max-line-length=120"
+  ],
+  "python.testing.pytestArgs": [
+    "pkg-py"
+  ],
+  "python.testing.unittestEnabled": false,
+  "python.testing.pytestEnabled": true
 }

pkg-py/CHANGELOG.md

@@ -11,6 +11,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 * Added `querychat_reset_dashboard()` tool for easily resetting the dashboard filters when asked by the user. (#81)
 
+* Added `querychat.greeting()` to help you create a greeting message for your querychat bot. (#87)
+
 ## [0.2.2] - 2025-09-04
 
 * Fixed another issue with data sources that aren't already narwhals DataFrames (#83)

pkg-py/docs/index.qmd

@@ -81,13 +81,39 @@ These suggestions appear in the greeting and automatically populate the chat tex
 This gives the user a few ideas to explore on their own.
 You can see this behavior in our [`querychat template`](https://shiny.posit.co/py/templates/querychat/).
 
-If you need help coming up with a greeting, your own app can help you! Just launch it and paste this into the chat interface:
+### Generate a greeting
 
-> Help me create a greeting for your future users. Include some example questions. Format your suggested greeting as Markdown, in a code block.
+If you need help coming up with a greeting, you can use the `querychat.greeting()` function to generate one:
 
-And keep giving it feedback until you're happy with the result, which will then be ready to be pasted into `greeting.md`.
+```python
+import querychat
+from palmerpenguins import load_penguins
+
+# Create config with your dataset
+penguins = load_penguins()
+penguins_config = querychat.init(penguins, "penguins")
+
+# Generate a greeting
+querychat.greeting(penguins_config)
+#> Hello! I'm here to help you explore and analyze the penguins dataset.
+#> Here are some example prompts you can try:
+#> ...
+
+# Update the config with the generated greeting
+penguins_config = querychat.init(
+    penguins,
+    "penguins",
+    greeting="Hello! I'm here to help you explore and analyze the penguins dataset..."
+)
+```
 
-Alternatively, you can completely suppress the greeting by passing `greeting=""`.
+This will use the LLM to generate a friendly greeting message with sample prompts.
+In Shiny apps, you could also generate the greeting once when the app starts up so that it's shared among all users:
+
+```python
+penguins_config = querychat.init(penguins, "penguins")
+penguins_config.greeting = querychat.greeting(penguins_config, echo="none")
+```
 
 ### Augment the system prompt (recommended)
 

pkg-py/src/querychat/__init__.py

@@ -1,3 +1,4 @@
+from querychat._greeting import greeting
 from querychat.querychat import (
     init,
     sidebar,
@@ -10,4 +11,4 @@
     mod_ui as ui,
 )
 
-__all__ = ["init", "server", "sidebar", "system_prompt", "ui"]
+__all__ = ["greeting", "init", "server", "sidebar", "system_prompt", "ui"]

pkg-py/src/querychat/_greeting.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+from copy import deepcopy
+
+
+def greeting(
+    querychat_config,
+    *,
+    generate: bool = True,
+    stream: bool = False,
+    **kwargs,
+) -> str | None:
+    """
+    Generate or retrieve a greeting message.
+
+    Use this function to generate a friendly greeting message using the chat
+    client and data source specified in the `querychat_config` object. You can
+    pass this greeting to `init()` to set an initial greeting for users for
+    faster startup times and lower costs. If you don't provide a greeting in
+    `init()`, one will be generated at the start of every new conversation.
+
+    Parameters
+    ----------
+    querychat_config
+        A QueryChatConfig object from `init()`.
+    generate
+        If `True` and if `querychat_config` does not include a `greeting`, a new
+        greeting is generated. If `False`, returns the existing greeting from
+        the configuration (if any).
+    stream
+        If `True`, returns a streaming response suitable for use in a Shiny app
+        with `chat_ui.append_message_stream()`. If `False` (default), returns
+        the full greeting at once. Only relevant when `generate = True`.
+    **kwargs
+        Additional arguments passed to the chat client's `chat()` or `stream_async()` method.
+
+    Returns
+    -------
+    str | None
+        - When `generate = False`: Returns the existing greeting as a string or
+          `None` if no greeting exists.
+        - When `generate = True`: Returns the chat response containing a greeting and
+          sample prompts.
+
+    Examples
+    --------
+    ```python
+    import pandas as pd
+    from querychat import init, greeting
+
+    # Create config with mtcars dataset
+    mtcars = pd.read_csv(
+        "https://gist.githubusercontent.com/seankross/a412dfbd88b3db70b74b/raw/5f23f993cd87c283ce766e7ac6b329ee7cc2e1d1/mtcars.csv"
+    )
+    mtcars_config = init(mtcars, "mtcars")
+
+    # Generate a new greeting
+    greeting_text = greeting(mtcars_config)
+
+    # Update the config with the generated greeting
+    mtcars_config = init(
+        mtcars,
+        "mtcars",
+        greeting="Hello! I'm here to help you explore and analyze the mtcars...",
+    )
+    ```
+
+    """
+    not_querychat_config = (
+        not hasattr(querychat_config, "client")
+        and not hasattr(querychat_config, "greeting")
+        and not hasattr(querychat_config, "system_prompt")
+    )
+
+    if not_querychat_config:
+        raise TypeError("`querychat_config` must be a QueryChatConfig object.")
+
+    greeting_text = querychat_config.greeting
+
+    if not generate:
+        has_greeting = greeting_text is not None and len(greeting_text.strip()) > 0
+        return greeting_text if has_greeting else None
+
+    chat = deepcopy(querychat_config.client)
+    chat.system_prompt = querychat_config.system_prompt
+
+    prompt = "Please give me a friendly greeting. Include a few sample prompts in a two-level bulleted list."
+
+    if stream:
+        return chat.stream_async(prompt, **kwargs)
+    else:
+        return chat.chat(prompt, **kwargs)

pkg-py/src/querychat/querychat.py

@@ -295,9 +295,12 @@ def init(
         have to be). If a data_source is a SQLAlchemy engine, the table_name is
         the name of the table in the database to query against.
     greeting : str | Path, optional
-        A string in Markdown format, containing the initial message.
-        If a pathlib.Path object is passed,
-        querychat will read the contents of the path into a string with `.read_text()`.
+        A string in Markdown format, containing the initial message. If a
+        pathlib.Path object is passed, querychat will read the contents of the
+        path into a string with `.read_text()`. You can use
+        `querychat.greeting()` to help generate a greeting from a querychat
+        configuration. If no greeting is provided, one will be generated at the
+        start of every new conversation.
     data_description : str | Path, optional
         Description of the data in plain text or Markdown.
         If a pathlib.Path object is passed,
@@ -375,6 +378,7 @@ def init(
         print(
             "Warning: No greeting provided; the LLM will be invoked at conversation start to generate one. "
             "For faster startup, lower cost, and determinism, please save a greeting and pass it to init().",
+            "You can also use `querychat.greeting()` to help generate a greeting.",
             file=sys.stderr,
         )
 

pkg-py/tests/test_greeting.py

@@ -0,0 +1,92 @@
+import os
+
+import pandas as pd
+import pytest
+
+from querychat import greeting, init
+
+
+@pytest.fixture(autouse=True)
+def set_dummy_api_key():
+    """Set a dummy OpenAI API key for testing."""
+    old_api_key = os.environ.get("OPENAI_API_KEY")
+    os.environ["OPENAI_API_KEY"] = "sk-dummy-api-key-for-testing"
+    yield
+    if old_api_key is not None:
+        os.environ["OPENAI_API_KEY"] = old_api_key
+    else:
+        del os.environ["OPENAI_API_KEY"]
+
+
+@pytest.fixture
+def querychat_config():
+    """Create a test querychat configuration."""
+    # Create a simple pandas DataFrame
+    df = pd.DataFrame(
+        {
+            "id": [1, 2, 3],
+            "name": ["Alice", "Bob", "Charlie"],
+            "age": [25, 30, 35],
+        },
+    )
+
+    # Create a config with a greeting
+    return init(
+        data_source=df,
+        table_name="test_table",
+        greeting="Hello! This is a test greeting.",
+    )
+
+
+@pytest.fixture
+def querychat_config_no_greeting():
+    """Create a test querychat configuration without a greeting."""
+    # Create a simple pandas DataFrame
+    df = pd.DataFrame(
+        {
+            "id": [1, 2, 3],
+            "name": ["Alice", "Bob", "Charlie"],
+            "age": [25, 30, 35],
+        },
+    )
+
+    # Create a config without a greeting
+    return init(
+        data_source=df,
+        table_name="test_table",
+        greeting=None,
+    )
+
+
+def test_greeting_retrieval(querychat_config):
+    """
+    Test that greeting() returns the existing greeting when generate=False.
+    """
+    result = greeting(querychat_config, generate=False)
+    assert result == "Hello! This is a test greeting."
+
+
+def test_greeting_retrieval_none(querychat_config_no_greeting):
+    """
+    Test that greeting() returns None when there's no existing greeting and
+    generate=False.
+    """
+    result = greeting(querychat_config_no_greeting, generate=False)
+    assert result is None
+
+
+def test_greeting_retrieval_empty(querychat_config):
+    """
+    Test that greeting() returns None when the existing greeting is empty and
+    generate=False.
+    """
+    querychat_config.greeting = ""
+
+    result = greeting(querychat_config, generate=False)
+    assert result is None
+
+
+def test_greeting_invalid_config():
+    """Test that greeting() raises TypeError when given an invalid config."""
+    with pytest.raises(TypeError):
+        greeting("not a config")

pkg-r/.Rbuildignore

@@ -0,0 +1,2 @@
+^pkgdown$
+^LICENSE\.md$

pkg-r/LICENSE

@@ -1,2 +1,2 @@
 YEAR: 2025
-COPYRIGHT HOLDER: Posit Software, PBC
+COPYRIGHT HOLDER: querychat authors

pkg-r/LICENSE.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2025 querychat authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.