diff --git a/pkg-py/CHANGELOG.md b/pkg-py/CHANGELOG.md
index 08b25af7..2c33cdf5 100644
--- a/pkg-py/CHANGELOG.md
+++ b/pkg-py/CHANGELOG.md
@@ -13,6 +13,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
### New features
+* New `QueryChat.app()` method enables quicker/easier chatting with a dataset. (#104)
+
+* Enabled bookmarking by default in both `.app()` and `.server()` methods. In latter case, you'll need to also specify the `bookmark_store` (either in `shiny.App()` or `shiny.express.app_opts()`) for it to take effect. (#104)
+
* The current SQL query and title can now be programmatically set through the `.sql()` and `.title()` methods of `QueryChat()`. (#98, #101)
* Added a `.generate_greeting()` method to help you create a greeting message for your querychat bot. (#87)
diff --git a/pkg-py/src/querychat/_icons.py b/pkg-py/src/querychat/_icons.py
new file mode 100644
index 00000000..2b7683da
--- /dev/null
+++ b/pkg-py/src/querychat/_icons.py
@@ -0,0 +1,20 @@
+from typing import Literal
+
+from shiny import ui
+
+ICON_NAMES = Literal["arrow-counterclockwise", "funnel-fill", "terminal-fill", "table"]
+
+
+def bs_icon(name: ICON_NAMES) -> ui.HTML:
+ """Get Bootstrap icon SVG by name."""
+ if name not in BS_ICONS:
+ raise ValueError(f"Unknown Bootstrap icon: {name}")
+ return ui.HTML(BS_ICONS[name])
+
+
+BS_ICONS = {
+ "arrow-counterclockwise": '',
+ "funnel-fill": '',
+ "terminal-fill": '',
+ "table": '',
+}
diff --git a/pkg-py/src/querychat/_querychat.py b/pkg-py/src/querychat/_querychat.py
index 7cc27462..3e4f59f5 100644
--- a/pkg-py/src/querychat/_querychat.py
+++ b/pkg-py/src/querychat/_querychat.py
@@ -10,9 +10,12 @@
import chatlas
import chevron
import sqlalchemy
-from shiny import ui
+from shiny import App, Inputs, Outputs, Session, reactive, render, req, ui
+from shiny.express._stub_session import ExpressStubSession
from shiny.session import get_current_session
+from shinychat import output_markdown_stream
+from ._icons import bs_icon
from ._querychat_module import ModServerResult, mod_server, mod_ui
from .datasource import DataFrameSource, DataSource, SQLAlchemySource
@@ -133,6 +136,99 @@ def __init__(
# Populated when ._server() gets called (in an active session)
self._server_values: ModServerResult | None = None
+ def app(
+ self, *, bookmark_store: Literal["url", "server", "disable"] = "url"
+ ) -> App:
+ """
+ Quickly chat with a dataset.
+
+ Creates a Shiny app with a chat sidebar and data table view -- providing a
+ quick-and-easy way to start chatting with your data.
+
+ Parameters
+ ----------
+ bookmark_store
+ The bookmarking store to use for the Shiny app. Options are:
+ - `"url"`: Store bookmarks in the URL (default).
+ - `"server"`: Store bookmarks on the server.
+ - `"disable"`: Disable bookmarking.
+
+ Returns
+ -------
+ :
+ A Shiny App object that can be run with `app.run()` or served with `shiny run`.
+
+ """
+ enable_bookmarking = bookmark_store != "disable"
+ table_name = self.data_source.table_name
+
+ def app_ui(request):
+ return ui.page_sidebar(
+ self.sidebar(),
+ ui.card(
+ ui.card_header(
+ ui.div(
+ ui.div(
+ bs_icon("terminal-fill"),
+ ui.output_text("query_title", inline=True),
+ class_="d-flex align-items-center gap-2",
+ ),
+ ui.output_ui("ui_reset", inline=True),
+ class_="hstack gap-3",
+ ),
+ ),
+ ui.output_ui("sql_output"),
+ fill=False,
+ style="max-height: 33%;",
+ ),
+ ui.card(
+ ui.card_header(bs_icon("table"), " Data"),
+ ui.output_data_frame("dt"),
+ ),
+ title=ui.span("querychat with ", ui.code(table_name)),
+ class_="bslib-page-dashboard",
+ fillable=True,
+ )
+
+ def app_server(input: Inputs, output: Outputs, session: Session):
+ self._server(enable_bookmarking=enable_bookmarking)
+
+ @render.text
+ def query_title():
+ return self.title() or "SQL Query"
+
+ @render.ui
+ def ui_reset():
+ req(self.sql())
+ return ui.input_action_button(
+ "reset_query",
+ "Reset Query",
+ class_="btn btn-outline-danger btn-sm lh-1 ms-auto",
+ )
+
+ @reactive.effect
+ @reactive.event(input.reset_query)
+ def _():
+ self.sql("")
+ self.title(None)
+
+ @render.data_frame
+ def dt():
+ return self.df()
+
+ @render.ui
+ def sql_output():
+ sql = self.sql() or f"SELECT * FROM {table_name}"
+ sql_code = f"```sql\n{sql}\n```"
+ return output_markdown_stream(
+ "sql_code",
+ content=sql_code,
+ auto_scroll=False,
+ width="100%",
+ )
+
+ return App(app_ui, app_server, bookmark_store=bookmark_store)
+
def sidebar(
self,
*,
@@ -183,7 +279,7 @@ def ui(self, **kwargs):
"""
return mod_ui(self.id, **kwargs)
- def _server(self):
+ def _server(self, *, enable_bookmarking: bool = False) -> None:
"""
Initialize the server module.
@@ -211,6 +307,7 @@ def _server(self):
system_prompt=self.system_prompt,
greeting=self.greeting,
client=self.client,
+ enable_bookmarking=enable_bookmarking,
)
return
@@ -434,7 +531,7 @@ def set_client(self, client: str | chatlas.Chat) -> None:
class QueryChat(QueryChatBase):
- def server(self):
+ def server(self, *, enable_bookmarking: bool = False) -> None:
"""
Initialize Shiny server logic.
@@ -443,29 +540,48 @@ def server(self):
Express mode, you can use `querychat.express.QueryChat` instead
of `querychat.QueryChat`, which calls `.server()` automatically.
+ Parameters
+ ----------
+ enable_bookmarking
+ Whether to enable bookmarking for the querychat module.
+
Examples
--------
```python
from shiny import App, render, ui
+ from seaborn import load_dataset
from querychat import QueryChat
- qc = QueryChat(my_dataframe, "my_data")
+ titanic = load_dataset("titanic")
- app_ui = ui.page_fluid(
- qc.sidebar(),
- ui.output_data_frame("data_table"),
- )
+ qc = QueryChat(titanic, "titanic")
+
+
+ def app_ui(request):
+ return ui.page_sidebar(
+ qc.sidebar(),
+ ui.card(
+ ui.card_header(ui.output_text("title")),
+ ui.output_data_frame("data_table"),
+ ),
+ title="Titanic QueryChat App",
+ fillable=True,
+ )
def server(input, output, session):
- qc.server()
+ qc.server(enable_bookmarking=True)
@render.data_frame
def data_table():
return qc.df()
+ @render.text
+ def title():
+ return qc.title() or "My Data"
- app = App(app_ui, server)
+
+ app = App(app_ui, server, bookmark_store="url")
```
Returns
@@ -474,7 +590,7 @@ def data_table():
None
"""
- return self._server()
+ return self._server(enable_bookmarking=enable_bookmarking)
class QueryChatExpress(QueryChatBase):
@@ -488,17 +604,33 @@ class QueryChatExpress(QueryChatBase):
Examples
--------
```python
- from shiny.express import render, ui
from querychat.express import QueryChat
+ from seaborn import load_dataset
+ from shiny.express import app_opts, render, ui
- qc = QueryChat(my_dataframe, "my_data")
+ titanic = load_dataset("titanic")
+ qc = QueryChat(titanic, "titanic")
qc.sidebar()
+ with ui.card(fill=True):
+ with ui.card_header():
+
+ @render.text
+ def title():
+ return qc.title() or "Titanic Dataset"
+
+ @render.data_frame
+ def data_table():
+ return qc.df()
- @render.data_frame
- def data_table():
- return qc.df()
+
+ ui.page_opts(
+ title="Titanic QueryChat App",
+ fillable=True,
+ )
+
+ app_opts(bookmark_store="url")
```
"""
@@ -514,6 +646,7 @@ def __init__(
data_description: Optional[str | Path] = None,
extra_instructions: Optional[str | Path] = None,
prompt_template: Optional[str | Path] = None,
+ enable_bookmarking: Literal["auto", True, False] = "auto",
):
super().__init__(
data_source,
@@ -525,7 +658,21 @@ def __init__(
extra_instructions=extra_instructions,
prompt_template=prompt_template,
)
- self._server()
+
+ # If the Express session has a bookmark store set, automatically enable
+ # querychat's bookmarking
+ enable: bool
+ if enable_bookmarking == "auto":
+ session = get_current_session()
+ if session and isinstance(session, ExpressStubSession):
+ store = session.app_opts.get("bookmark_store", "disable")
+ enable = store != "disable"
+ else:
+ enable = False
+ else:
+ enable = enable_bookmarking
+
+ self._server(enable_bookmarking=enable)
def normalize_data_source(
diff --git a/pkg-py/src/querychat/_querychat_module.py b/pkg-py/src/querychat/_querychat_module.py
index 2fe0f3cd..6153a5b8 100644
--- a/pkg-py/src/querychat/_querychat_module.py
+++ b/pkg-py/src/querychat/_querychat_module.py
@@ -14,6 +14,7 @@
import chatlas
import pandas as pd
from shiny import Inputs, Outputs, Session
+ from shiny.bookmark import BookmarkState, RestoreState
from .datasource import DataSource
@@ -60,10 +61,12 @@ def mod_server(
system_prompt: str,
greeting: str | None,
client: chatlas.Chat,
+ enable_bookmarking: bool,
):
# Reactive values to store state
sql = ReactiveString("")
title = ReactiveStringOrNone(None)
+ has_greeted = reactive.value[bool](False) # noqa: FBT003
# Set up the chat object for this session
chat = copy.deepcopy(client)
@@ -99,6 +102,9 @@ async def _(user_input: str):
@reactive.effect
async def greet_on_startup():
+ if has_greeted():
+ return
+
if greeting:
await chat_ui.append_message(greeting)
elif greeting is None:
@@ -108,6 +114,8 @@ async def greet_on_startup():
)
await chat_ui.append_message_stream(stream)
+ has_greeted.set(True)
+
# Handle update button clicks
@reactive.effect
@reactive.event(input.chat_update)
@@ -125,4 +133,24 @@ def _():
if new_title is not None:
title.set(new_title)
+ if enable_bookmarking:
+ chat_ui.enable_bookmarking(client)
+
+ @session.bookmark.on_bookmark
+ def _on_bookmark(x: BookmarkState) -> None:
+ vals = x.values # noqa: PD011
+ vals["querychat_sql"] = sql.get()
+ vals["querychat_title"] = title.get()
+ vals["querychat_has_greeted"] = has_greeted.get()
+
+ @session.bookmark.on_restore
+ def _on_restore(x: RestoreState) -> None:
+ vals = x.values # noqa: PD011
+ if "querychat_sql" in vals:
+ sql.set(vals["querychat_sql"])
+ if "querychat_title" in vals:
+ title.set(vals["querychat_title"])
+ if "querychat_has_greeted" in vals:
+ has_greeted.set(vals["querychat_has_greeted"])
+
return ModServerResult(df=filtered_df, sql=sql, title=title, client=chat)
diff --git a/pkg-py/src/querychat/tools.py b/pkg-py/src/querychat/tools.py
index 8e88bc0d..d908364a 100644
--- a/pkg-py/src/querychat/tools.py
+++ b/pkg-py/src/querychat/tools.py
@@ -5,9 +5,9 @@
import chevron
from chatlas import ContentToolResult, Tool
-from htmltools import HTML
from shinychat.types import ToolResultDisplay
+from ._icons import bs_icon
from ._utils import df_to_html
if TYPE_CHECKING:
@@ -66,9 +66,7 @@ def update_dashboard(query: str, title: str) -> ContentToolResult:
title=title,
show_request=False,
open=True,
- icon=HTML(
- '',
- ),
+ icon=bs_icon("funnel-fill"),
),
},
)
@@ -142,9 +140,7 @@ def reset_dashboard() -> ContentToolResult:
title=None,
show_request=False,
open=False,
- icon=HTML(
- '',
- ),
+ icon=bs_icon("arrow-counterclockwise"),
),
},
)
@@ -213,9 +209,7 @@ def query(query: str, _intent: str = "") -> ContentToolResult:
markdown=markdown,
show_request=False,
open=True,
- icon=HTML(
- '',
- ),
+ icon=bs_icon("table"),
),
},
)