querychat 0.1.0__tar.gz

querychat-0.1.0/.gitignore

@@ -0,0 +1,4 @@
+__pycache__/
+animation.screenflow/
+README_files/
+README.html

querychat-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2025 Posit Software, PBC
+
+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.

querychat-0.1.0/PKG-INFO

@@ -0,0 +1,165 @@
+Metadata-Version: 2.4
+Name: querychat
+Version: 0.1.0
+Summary: Chat with your data using natural language
+Project-URL: Homepage, https://github.com/posit-dev/querychat
+Project-URL: Issues, https://github.com/posit-dev/querychat/issues
+Project-URL: Source, https://github.com/posit-dev/querychat/tree/main/python-package
+Author-email: Posit <info@posit.co>
+License: # MIT License
+        
+        Copyright (c) 2025 Posit Software, PBC
+        
+        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.
+License-File: LICENSE
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.8
+Requires-Dist: chatlas
+Requires-Dist: duckdb
+Requires-Dist: htmltools
+Requires-Dist: narwhals
+Requires-Dist: pandas
+Requires-Dist: shiny
+Requires-Dist: shinywidgets
+Description-Content-Type: text/markdown
+
+# querychat for Python
+
+Chat with your Shiny Python apps using natural language.
+
+Imagine typing questions like these directly into your Shiny dashboard, and seeing the results in realtime:
+
+* "Show only data from 2008 with highway MPG greater than 30."
+* "What's the average city MPG for SUVs vs compact cars?"
+* "Sort the data by highway fuel efficiency descending."
+
+## Installation
+
+```bash
+pip install "querychat @ git+https://github.com/posit-dev/querychat#subdirectory=python-package"
+```
+
+## How to use
+
+First, you'll need access to an LLM that supports tools/function calling. querychat uses [chatlas](https://github.com/posit-dev/chatlas) to interface with various providers.
+
+Here's a minimal example (see [examples/app.py](examples/app.py) for an unabridged version):
+
+```python
+from pathlib import Path
+
+from seaborn import load_dataset
+from shiny import App, render, ui
+
+import querychat
+
+titanic = load_dataset("titanic")
+
+# 1. Configure querychat
+querychat_config = querychat.init(titanic, "titanic")
+
+# Create UI
+app_ui = ui.page_sidebar(
+    # 2. Place the chat component in the sidebar
+    querychat.sidebar("chat"),
+    # Main panel with data viewer
+    ui.output_data_frame("data_table"),
+    title="querychat with Python",
+    fillable=True,
+)
+
+
+# Define server logic
+def server(input, output, session):
+    # 3. Initialize querychat server with the config from step 1
+    chat = querychat.server("chat", querychat_config)
+
+    # 4. Display the filtered dataframe
+    @render.data_frame
+    def data_table():
+        # Access filtered data via chat.df() reactive
+        return chat["df"]()
+
+
+# Create Shiny app
+app = App(app_ui, server)
+```
+
+## Features
+
+querychat uses LLMs to generate SQL queries from natural language, offering:
+
+- **Reliability**: LLMs are excellent at writing SQL but bad at direct calculation
+- **Transparency**: SQL is always displayed to the user
+- **Reproducibility**: Generated SQL can be copied and reused elsewhere
+
+## Customization
+
+### Configure with your own data
+
+```python
+querychat_config = querychat.init(
+    df=my_dataframe,
+    table_name="my_data",  # Optional: defaults to "data"
+    greeting="Welcome! Ask me anything about the data.",
+    data_description="""
+    This dataset contains information about...
+    - column1: Description of column 1
+    - column2: Description of column 2
+    """,
+    extra_instructions="Please use British English spelling conventions."
+)
+```
+
+### Use a different LLM provider
+
+You can change the LLM provider or model by providing a callback function that takes a `system_prompt` argument and returns a `chatlas.Chat` object. (The parameter must be called  `system_prompt` as it is passed by keyword.)
+
+```python
+import chatlas
+
+def my_chat_func(system_prompt: str) -> chatlas.Chat:
+    return chatlas.ChatAnthropic(
+        model="claude-3-5-sonnet-latest",
+        system_prompt=system_prompt
+    )
+
+querychat_config = querychat.init(
+    df=my_dataframe,
+    create_chat_callback=my_chat_func
+)
+```
+
+## How it works
+
+querychat works by:
+
+1. Converting your pandas DataFrame to a DuckDB table
+2. Creating a system prompt with your data schema
+3. Setting up tools that let the LLM execute SQL queries
+4. Processing natural language to SQL queries
+5. Returning filtered data to your Shiny app
+
+See the `examples/` directory for more complete examples.

querychat-0.1.0/README.md

@@ -0,0 +1,118 @@
+# querychat for Python
+
+Chat with your Shiny Python apps using natural language.
+
+Imagine typing questions like these directly into your Shiny dashboard, and seeing the results in realtime:
+
+* "Show only data from 2008 with highway MPG greater than 30."
+* "What's the average city MPG for SUVs vs compact cars?"
+* "Sort the data by highway fuel efficiency descending."
+
+## Installation
+
+```bash
+pip install "querychat @ git+https://github.com/posit-dev/querychat#subdirectory=python-package"
+```
+
+## How to use
+
+First, you'll need access to an LLM that supports tools/function calling. querychat uses [chatlas](https://github.com/posit-dev/chatlas) to interface with various providers.
+
+Here's a minimal example (see [examples/app.py](examples/app.py) for an unabridged version):
+
+```python
+from pathlib import Path
+
+from seaborn import load_dataset
+from shiny import App, render, ui
+
+import querychat
+
+titanic = load_dataset("titanic")
+
+# 1. Configure querychat
+querychat_config = querychat.init(titanic, "titanic")
+
+# Create UI
+app_ui = ui.page_sidebar(
+    # 2. Place the chat component in the sidebar
+    querychat.sidebar("chat"),
+    # Main panel with data viewer
+    ui.output_data_frame("data_table"),
+    title="querychat with Python",
+    fillable=True,
+)
+
+
+# Define server logic
+def server(input, output, session):
+    # 3. Initialize querychat server with the config from step 1
+    chat = querychat.server("chat", querychat_config)
+
+    # 4. Display the filtered dataframe
+    @render.data_frame
+    def data_table():
+        # Access filtered data via chat.df() reactive
+        return chat["df"]()
+
+
+# Create Shiny app
+app = App(app_ui, server)
+```
+
+## Features
+
+querychat uses LLMs to generate SQL queries from natural language, offering:
+
+- **Reliability**: LLMs are excellent at writing SQL but bad at direct calculation
+- **Transparency**: SQL is always displayed to the user
+- **Reproducibility**: Generated SQL can be copied and reused elsewhere
+
+## Customization
+
+### Configure with your own data
+
+```python
+querychat_config = querychat.init(
+    df=my_dataframe,
+    table_name="my_data",  # Optional: defaults to "data"
+    greeting="Welcome! Ask me anything about the data.",
+    data_description="""
+    This dataset contains information about...
+    - column1: Description of column 1
+    - column2: Description of column 2
+    """,
+    extra_instructions="Please use British English spelling conventions."
+)
+```
+
+### Use a different LLM provider
+
+You can change the LLM provider or model by providing a callback function that takes a `system_prompt` argument and returns a `chatlas.Chat` object. (The parameter must be called  `system_prompt` as it is passed by keyword.)
+
+```python
+import chatlas
+
+def my_chat_func(system_prompt: str) -> chatlas.Chat:
+    return chatlas.ChatAnthropic(
+        model="claude-3-5-sonnet-latest",
+        system_prompt=system_prompt
+    )
+
+querychat_config = querychat.init(
+    df=my_dataframe,
+    create_chat_callback=my_chat_func
+)
+```
+
+## How it works
+
+querychat works by:
+
+1. Converting your pandas DataFrame to a DuckDB table
+2. Creating a system prompt with your data schema
+3. Setting up tools that let the LLM execute SQL queries
+4. Processing natural language to SQL queries
+5. Returning filtered data to your Shiny app
+
+See the `examples/` directory for more complete examples.

querychat-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "querychat"
+version = "0.1.0"
+description = "Chat with your data using natural language"
+readme = "README.md"
+requires-python = ">=3.8"
+license = {file = "LICENSE"}
+authors = [
+    {name = "Posit", email = "info@posit.co"},
+]
+dependencies = [
+    "duckdb",
+    "pandas",
+    "shiny",
+    "shinywidgets",
+    "htmltools",
+    "chatlas",
+    "narwhals",
+]
+
+classifiers = [
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+
+[project.urls]
+Homepage = "https://github.com/posit-dev/querychat"
+Issues = "https://github.com/posit-dev/querychat/issues"
+Source = "https://github.com/posit-dev/querychat/tree/main/python-package"
+
+[tool.hatch.build.targets.wheel]
+packages = ["querychat"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "querychat",
+    "LICENSE",
+    "README.md",
+]

querychat-0.1.0/src/querychat/__init__.py

@@ -0,0 +1,3 @@
+from querychat.querychat import init, ui, sidebar, server
+
+__all__ = ["init", "ui", "sidebar", "server"]

querychat-0.1.0/src/querychat/prompt/prompt.md

@@ -0,0 +1,91 @@
+You are a chatbot that is displayed in the sidebar of a data dashboard. You will be asked to perform various tasks on the data, such as filtering, sorting, and answering questions.
+
+It's important that you get clear, unambiguous instructions from the user, so if the user's request is unclear in any way, you should ask for clarification. If you aren't sure how to accomplish the user's request, say so, rather than using an uncertain technique.
+
+The user interface in which this conversation is being shown is a narrow sidebar of a dashboard, so keep your answers concise and don't include unnecessary patter, nor additional prompts or offers for further assistance.
+
+You have at your disposal a DuckDB database containing this schema:
+
+{{schema}}
+
+For security reasons, you may only query this specific table.
+
+{{data_description}}
+
+There are several tasks you may be asked to do:
+
+## Task: Filtering and sorting
+
+The user may ask you to perform filtering and sorting operations on the dashboard; if so, your job is to write the appropriate SQL query for this database. Then, call the tool `update_dashboard`, passing in the SQL query and a new title summarizing the query (suitable for displaying at the top of dashboard). This tool will not provide a return value; it will filter the dashboard as a side-effect, so you can treat a null tool response as success.
+
+* **Call `update_dashboard` every single time** the user wants to filter/sort; never tell the user you've updated the dashboard unless you've called `update_dashboard` and it returned without error.
+* The SQL query must be a **DuckDB SQL** SELECT query. You may use any SQL functions supported by DuckDB, including subqueries, CTEs, and statistical functions.
+* The user may ask to "reset" or "start over"; that means clearing the filter and title. Do this by calling `update_dashboard({"query": "", "title": ""})`.
+* Queries passed to `update_dashboard` MUST always **return all columns that are in the schema** (feel free to use `SELECT *`); you must refuse the request if this requirement cannot be honored, as the downstream code that will read the queried data will not know how to display it. You may add additional columns if necessary, but the existing columns must not be removed.
+* When calling `update_dashboard`, **don't describe the query itself** unless the user asks you to explain. Don't pretend you have access to the resulting data set, as you don't.
+
+For reproducibility, follow these rules as well:
+
+* Optimize the SQL query for **readability over efficiency**.
+* Always filter/sort with a **single SQL query** that can be passed directly to `update_dashboard`, even if that SQL query is very complicated. It's fine to use subqueries and common table expressions.
+    * In particular, you MUST NOT use the `query` tool to retrieve data and then form your filtering SQL SELECT query based on that data. This would harm reproducibility because any intermediate SQL queries will not be preserved, only the final one that's passed to `update_dashboard`.
+    * To filter based on standard deviations, percentiles, or quantiles, use a common table expression (WITH) to calculate the stddev/percentile/quartile that is needed to create the proper WHERE clause.
+    * Include comments in the SQL to explain what each part of the query does.
+
+Example of filtering and sorting:
+
+> [User]  
+> Show only rows where the value of x is greater than average.  
+> [/User]  
+> [ToolCall]  
+> update_dashboard({query: "SELECT * FROM table\nWHERE x > (SELECT AVG(x) FROM table)", title: "Above average x values"})  
+> [/ToolCall]  
+> [ToolResponse]  
+> null  
+> [/ToolResponse]  
+> [Assistant]  
+> I've filtered the dashboard to show only rows where the value of x is greater than average.  
+> [/Assistant]
+
+## Task: Answering questions about the data
+
+The user may ask you questions about the data. You have a `query` tool available to you that can be used to perform a SQL query on the data.
+
+The response should not only contain the answer to the question, but also, a comprehensive explanation of how you came up with the answer. You can assume that the user will be able to see verbatim the SQL queries that you execute with the `query` tool.
+
+Always use SQL to count, sum, average, or otherwise aggregate the data. Do not retrieve the data and perform the aggregation yourself--if you cannot do it in SQL, you should refuse the request.
+
+Example of question answering:
+
+> [User]  
+> What are the average values of x and y?  
+> [/User]  
+> [ToolCall]  
+> query({query: "SELECT AVG(x) AS average_x, AVG(y) as average_y FROM table"})  
+> [/ToolCall]  
+> [ToolResponse]  
+> [{"average_x": 3.14, "average_y": 6.28}]  
+> [/ToolResponse]  
+> [Assistant]  
+> The average value of x is 3.14. The average value of y is 6.28.  
+> [/Assistant]
+
+## Task: Providing general help
+
+If the user provides a vague help request, like "Help" or "Show me instructions", describe your own capabilities in a helpful way, including examples of questions they can ask. Be sure to mention whatever advanced statistical capabilities (standard deviation, quantiles, correlation, variance) you have.
+
+### Showing example questions
+
+If you find yourself offering example questions to the user as part of your response, wrap the text of each prompt in `<span class="suggestion">` tags. For example:
+
+```
+* <span class="suggestion">Suggestion 1.</span>
+* <span class="suggestion">Suggestion 2.</span>
+* <span class="suggestion">Suggestion 3.</span>
+```
+
+## DuckDB SQL tips
+
+* `percentile_cont` and `percentile_disc` are "ordered set" aggregate functions. These functions are specified using the WITHIN GROUP (ORDER BY sort_expression) syntax, and they are converted to an equivalent aggregate function that takes the ordering expression as the first argument. For example, `percentile_cont(fraction) WITHIN GROUP (ORDER BY column [(ASC|DESC)])` is equivalent to `quantile_cont(column, fraction ORDER BY column [(ASC|DESC)])`.
+
+{{extra_instructions}}