13 | Joe Cheng:
14 | href: https://github.com/jcheng5
15 | Carson Sievert:
16 | href: https://cpsievert.me
17 | Garrick Aden-Buie:
18 | href: https://garrickadenbuie.com
19 | Barret Schloerke:
20 | href: https://schloerke.com/
21 | Daniel Chen:
22 | href: https://chendaniely.github.io
23 |
24 | template:
25 | bootstrap: 5
26 | light-switch: true
27 | theme: github-light
28 | theme-dark: github-dark
29 | bslib:
30 | brand: pkgdown/_brand.yml
31 |
32 | navbar:
33 | structure:
34 | left: [get-started, articles, reference, news]
35 | right: [search, github, lightswitch]
36 | components:
37 | home: ~
38 |
39 | reference:
40 | - title: Chat interfaces
41 | contents:
42 | - querychat
43 | - QueryChat
44 |
45 | - title: Data Sources
46 | contents:
47 | - DataSource
48 | - DataFrameSource
49 | - DBISource
50 |
--------------------------------------------------------------------------------
/pkg-r/inst/prompts/tool-update-dashboard.md:
--------------------------------------------------------------------------------
1 | Filter and sort the dashboard data
2 |
3 | This tool executes a {{db_type}} SQL SELECT `query` to filter or sort the data used in the dashboard.
4 |
5 | **Returns:** A confirmation that the dashboard was updated successfully, or the error that occurred when running the SQL query. The results of the query will update the data shown in the dashboard.
6 |
7 | **When to use:** Call this tool whenever the user requests filtering, sorting, or data manipulation on the dashboard with questions like "Show me..." or "Which records have...". This tool is appropriate for any request that involves showing a subset of the data or reordering it.
8 |
9 | **When not to use:** Do NOT use this tool for general questions about the data that can be answered with a single value or summary statistic. For those questions, use the `querychat_query` tool instead.
10 |
11 | **Important constraints:**
12 |
13 | - All original schema columns must be present in the SELECT output
14 | - Use a single SQL query. You can use CTEs but you cannot chain multiple queries
15 | - For statistical filters (stddev, percentiles), use CTEs to calculate thresholds within the query
16 | - Assume the user will only see the original columns in the dataset
17 |
18 |
--------------------------------------------------------------------------------
/pkg-r/man/figures/lifecycle-deprecated.svg:
--------------------------------------------------------------------------------
1 |
22 |
--------------------------------------------------------------------------------
/pkg-r/man/figures/lifecycle-superseded.svg:
--------------------------------------------------------------------------------
1 |
22 |
--------------------------------------------------------------------------------
/pkg-py/examples/data_description.md:
--------------------------------------------------------------------------------
1 | # Data Dictionary
2 |
3 | - **survival**: Survival status
4 | - 0 = No
5 | - 1 = Yes
6 |
7 | - **pclass**: Ticket class
8 | - 1 = 1st class
9 | - 2 = 2nd class
10 | - 3 = 3rd class
11 |
12 | - **sex**: Sex of the passenger
13 |
14 | - **age**: Age in years
15 |
16 | - **sibsp**: Number of siblings or spouses aboard the Titanic
17 |
18 | - **parch**: Number of parents or children aboard the Titanic
19 |
20 | - **ticket**: Ticket number
21 |
22 | - **fare**: Passenger fare
23 |
24 | - **cabin**: Cabin number
25 |
26 | - **embarked**: Port of embarkation
27 | - C = Cherbourg
28 | - Q = Queenstown
29 | - S = Southampton
30 |
31 | ## Variable Notes
32 |
33 | - **pclass** is a proxy for socio-economic status (SES):
34 | - 1st = Upper class
35 | - 2nd = Middle class
36 | - 3rd = Lower class
37 |
38 | - **age**:
39 | - If less than 1 year old, age is fractional.
40 | - Estimated ages are represented as `xx.5`.
41 |
42 | - **sibsp**: Family relations are defined as:
43 | - Sibling = brother, sister, stepbrother, stepsister
44 | - Spouse = husband, wife (mistresses and fiancés were ignored)
45 |
46 | - **parch**: Family relations are defined as:
47 | - Parent = mother, father
48 | - Child = daughter, son, stepdaughter, stepson
49 | - Some children traveled only with a nanny, so `parch = 0` for them.
--------------------------------------------------------------------------------
/pkg-r/man/figures/lifecycle-experimental.svg:
--------------------------------------------------------------------------------
1 |
22 |
--------------------------------------------------------------------------------
/.github/workflows/py-release.yml:
--------------------------------------------------------------------------------
1 | name: Python - Release
2 |
3 | on:
4 | release:
5 | types: [published]
6 |
7 | env:
8 | PYTHON_VERSION: 3.12
9 |
10 | jobs:
11 | pypi-release:
12 | name: Build and release Python package
13 | runs-on: ubuntu-latest
14 |
15 | if: startsWith(github.ref, 'refs/tags/py/v')
16 |
17 | environment:
18 | name: pypi
19 | url: https://pypi.org/project/querychat/
20 |
21 | permissions: # for trusted publishing
22 | id-token: write
23 |
24 | steps:
25 | - uses: actions/checkout@v4
26 |
27 | - name: 🚀 Install uv
28 | uses: astral-sh/setup-uv@v3
29 |
30 | - name: 🐍 Set up Python ${{ env.PYTHON_VERSION }}
31 | run: uv python install ${{ env.PYTHON_VERSION }}
32 |
33 | - name: 📦 Install the project
34 | run: uv sync --python ${{ env.PYTHON_VERSION }} --all-extras --all-groups
35 |
36 | - name: 🧪 Check tests
37 | run: make py-check-tests
38 |
39 | - name: 📝 Check types
40 | run: make py-check-types
41 |
42 | - name: 📐 Check formatting
43 | run: make py-check-format
44 | - name: 🧳 Build package
45 | run: make py-build
46 |
47 | # TODO: https://pypi.org/manage/project/querychat/settings/publishing/
48 | - name: 🚢 Publish release on PyPI
49 | uses: pypa/gh-action-pypi-publish@release/v1
50 | with:
51 | packages-dir: ./dist
52 |
--------------------------------------------------------------------------------
/pkg-r/man/figures/lifecycle-stable.svg:
--------------------------------------------------------------------------------
1 |
30 |
--------------------------------------------------------------------------------
/pkg-r/R/utils-check.R:
--------------------------------------------------------------------------------
1 | # SQL table name validation ----------------------------------------------
2 |
3 | #' Check SQL table name validity
4 | #'
5 | #' Validates that a string is a valid SQL table name. A valid SQL table name
6 | #' must begin with a letter and contain only letters, numbers, and underscores.
7 | #'
8 | #' @param x The value to check
9 | #' @param ... These dots are for future extensions and must be empty.
10 | #' @param allow_null Logical. If `TRUE`, `NULL` is accepted as a valid value.
11 | #' @param arg Argument name to use in error messages
12 | #' @param call Calling environment for error messages
13 | #'
14 | #' @return Invisibly returns `NULL` if validation passes. Otherwise throws an error.
15 | #' @keywords internal
16 | #' @noRd
17 | check_sql_table_name <- function(
18 | x,
19 | ...,
20 | allow_null = FALSE,
21 | arg = caller_arg(x),
22 | call = caller_env()
23 | ) {
24 | check_dots_empty()
25 |
26 | # Check if NULL is allowed
27 | if (allow_null && is.null(x)) {
28 | return(invisible(NULL))
29 | }
30 |
31 | # First check it's a string
32 | check_string(x, allow_null = allow_null, arg = arg, call = call)
33 |
34 | # Then validate SQL table name pattern
35 | if (!grepl("^[a-zA-Z][a-zA-Z0-9_]*$", x)) {
36 | cli::cli_abort(
37 | c(
38 | "{.arg {arg}} must be a valid SQL table name",
39 | "i" = "Table names must begin with a letter and contain only letters, numbers, and underscores",
40 | "x" = "You provided: {.val {x}}"
41 | ),
42 | call = call
43 | )
44 | }
45 |
46 | invisible(NULL)
47 | }
48 |
--------------------------------------------------------------------------------
/pkg-py/docs/styles.scss:
--------------------------------------------------------------------------------
1 | /*-- scss:defaults --*/
2 |
3 | $font-family-sans-serif: 'Public Sans', sans-serif;
4 | $font-family-monospace: 'Fira Code', monospace;
5 | $headings-font-family: 'Hubot Sans', sans-serif;
6 | $display-font-family: 'Hubot Sans', sans-serif;
7 | $headings-color: #193D56;
8 |
9 | /*-- scss:rules --*/
10 |
11 | @import url('https://fonts.googleapis.com/css2?family=Public+Sans:ital,wght@0,100..900;1,100..900&display=swap');
12 | @import url('https://fonts.googleapis.com/css?family=Fira Code');
13 | @import url('https://fonts.googleapis.com/css?family=Hubot Sans');
14 |
15 | .header {
16 | font-family: $headings-font-family;
17 | color: $headings-color;
18 | }
19 |
20 | /* css styles */
21 |
22 | .cell-output pre code {
23 | white-space: pre-wrap;
24 | }
25 |
26 | /* Undo somebody's aggressive CSS */
27 | pre {
28 | font-family: var(--bs-font-monospace);
29 | }
30 |
31 |
32 | /* sidebar */
33 | .sidebar-item-container {
34 | font-size: 1rem;
35 |
36 | .text-start {
37 | font-weight: 600;
38 | }
39 | }
40 |
41 | .sidebar-item-section {
42 | padding-top: 0.5rem;
43 | }
44 |
45 | // make it even more noticable
46 | .sidebar-link {
47 | &:hover {
48 | font-weight: 500;
49 | }
50 |
51 | &.active {
52 | position: relative;
53 |
54 | &::before {
55 | content: "\23F5";
56 | position: absolute;
57 | left: -0.9em;
58 | font-size: 1em;
59 | color: var(--bs-primary);
60 | }
61 | }
62 | }
63 |
64 |
65 | /* Get code output to look like a sourceCode block */
66 | pre:has(> code) {
67 | background-color: rgba(233, 236, 239, 0.65);
68 | border-radius: .25em;
69 | padding: .4em;
70 | }
--------------------------------------------------------------------------------
/pkg-py/src/querychat/prompts/tool-update-dashboard.md:
--------------------------------------------------------------------------------
1 | Filter and sort the dashboard data
2 |
3 | This tool executes a {{db_type}} SQL SELECT query to filter or sort the data used in the dashboard.
4 |
5 | **When to use:** Call this tool whenever the user requests filtering, sorting, or data manipulation on the dashboard with questions like "Show me..." or "Which records have...". This tool is appropriate for any request that involves showing a subset of the data or reordering it.
6 |
7 | **When not to use:** Do NOT use this tool for general questions about the data that can be answered with a single value or summary statistic. For those questions, use the `querychat_query` tool instead.
8 |
9 | **Important constraints:**
10 |
11 | - All original schema columns must be present in the SELECT output
12 | - Use a single SQL query. You can use CTEs but you cannot chain multiple queries
13 | - For statistical filters (stddev, percentiles), use CTEs to calculate thresholds within the query
14 | - Assume the user will only see the original columns in the dataset
15 |
16 |
17 | Parameters
18 | ----------
19 | query :
20 | A {{db_type}} SQL SELECT query that MUST return all existing schema columns (use SELECT * or explicitly list all columns). May include additional computed columns, subqueries, CTEs, WHERE clauses, ORDER BY, and any {{db_type}}-supported SQL functions.
21 | title :
22 | A brief title for display purposes, summarizing the intent of the SQL query.
23 |
24 | Returns
25 | -------
26 | :
27 | A confirmation that the dashboard was updated successfully, or the error that occurred when running the SQL query. The results of the query will update the data shown in the dashboard.
28 |
29 |
--------------------------------------------------------------------------------
/pkg-r/R/utils-ellmer.R:
--------------------------------------------------------------------------------
1 | interpolate_package <- function(path, ..., .envir = parent.frame()) {
2 | # This helper replicates ellmer::interpolate_package() to work with load_all()
3 | stopifnot(
4 | "`path` must be a single string" = is.character(path),
5 | "`path` must be a single string" = length(path) == 1
6 | )
7 |
8 | path <- system.file("prompts", path, package = "querychat")
9 | stopifnot(
10 | "`path` does not exist" = nzchar(path),
11 | "`path` does not exist" = file.exists(path)
12 | )
13 |
14 | ellmer::interpolate_file(path, ..., .envir = .envir)
15 | }
16 |
17 |
18 | as_querychat_client <- function(client = NULL) {
19 | if (is.null(client)) {
20 | client <- querychat_client_option()
21 | }
22 |
23 | if (is.null(client)) {
24 | # Use OpenAI with ellmer's default model
25 | return(ellmer::chat_openai())
26 | }
27 |
28 | if (is_function(client)) {
29 | # `client` as a function was the first interface we supported and expected
30 | # `system_prompt` as an argument. This avoids breaking existing code.
31 | client <- client(system_prompt = NULL)
32 | }
33 |
34 | if (is_string(client)) {
35 | client <- ellmer::chat(client)
36 | }
37 |
38 | if (!inherits(client, "Chat")) {
39 | cli::cli_abort(
40 | "{.arg client} must be an {.pkg ellmer} {.cls Chat} object or a function that returns one"
41 | )
42 | }
43 |
44 | client
45 | }
46 |
47 | querychat_client_option <- function() {
48 | opt <- getOption("querychat.client", NULL)
49 | if (!is.null(opt)) {
50 | return(opt)
51 | }
52 |
53 | env <- Sys.getenv("QUERYCHAT_CLIENT", "")
54 | if (nzchar(env)) {
55 | return(env)
56 | }
57 |
58 | NULL
59 | }
60 |
--------------------------------------------------------------------------------
/pkg-r/inst/prompts/tool-query.md:
--------------------------------------------------------------------------------
1 | Execute a SQL query and return the results
2 |
3 | This tool executes a {{db_type}} SQL SELECT query against the database and returns the raw result data for analysis.
4 |
5 | **Returns:** The tabular data results from executing the SQL query. The query results will be visible to the user in the interface, so you must interpret and explain the data in natural language after receiving it.
6 |
7 | **When to use:** Call this tool whenever the user asks a question that requires data analysis, aggregation, or calculations. Use this for questions like:
8 | - "What is the average...?"
9 | - "How many records...?"
10 | - "Which item has the highest/lowest...?"
11 | - "What's the total sum of...?"
12 | - "What percentage of ...?"
13 |
14 | Always use SQL for counting, averaging, summing, and other calculations—NEVER attempt manual calculations on your own. Use this tool repeatedly if needed to avoid any kind of manual calculation.
15 |
16 | **When not to use:** Do NOT use this tool for filtering or sorting the dashboard display. If the user wants to "Show me..." or "Filter to..." certain records in the dashboard, use the `querychat_update_dashboard` tool instead.
17 |
18 | **Important guidelines:**
19 |
20 | - Queries must be valid {{db_type}} SQL SELECT statements
21 | - Optimize for readability over efficiency—use clear column aliases and SQL comments to explain complex logic
22 | - Subqueries and CTEs are acceptable and encouraged for complex calculations
23 | - After receiving results, provide an explanation of the answer and an overview of how you arrived at it, if not already explained in SQL comments
24 | - The user can see your SQL query, they will follow up with detailed explanations if needed
25 |
--------------------------------------------------------------------------------
/.github/workflows/py-test.yml:
--------------------------------------------------------------------------------
1 | name: Test - Python
2 |
3 | on:
4 | workflow_dispatch:
5 | push:
6 | branches: ["main", "rc-*"]
7 | paths:
8 | - 'pkg-py/**'
9 | - 'pyproject.toml'
10 | - '.github/workflows/py-test.yml'
11 | pull_request:
12 | types: [opened, synchronize, reopened, ready_for_review]
13 | paths:
14 | - 'pkg-py/**'
15 | - 'pyproject.toml'
16 | - '.github/workflows/py-test.yml'
17 | release:
18 | types: [published]
19 |
20 | permissions:
21 | contents: read
22 |
23 | jobs:
24 | test:
25 | runs-on: ubuntu-latest
26 | strategy:
27 | matrix:
28 | config:
29 | - { python-version: "3.10", test_google: false, test_azure: false }
30 | - { python-version: "3.11", test_google: false, test_azure: false }
31 | - { python-version: "3.12", test_google: true, test_azure: true }
32 | - { python-version: "3.13", test_google: false, test_azure: false }
33 | - { python-version: "3.14", test_google: false, test_azure: false }
34 | fail-fast: false
35 |
36 | steps:
37 | - uses: actions/checkout@v4
38 |
39 | - name: 🚀 Install uv
40 | uses: astral-sh/setup-uv@v3
41 |
42 | - name: 🐍 Set up Python ${{ matrix.config.python-version }}
43 | run: uv python install ${{matrix.config.python-version }}
44 |
45 | - name: 📦 Install the project
46 | run: uv sync --python ${{matrix.config.python-version }} --all-extras --all-groups
47 |
48 | - name: 🧪 Check tests
49 | run: make py-check-tests
50 |
51 | - name: 📝 Check types
52 | run: make py-check-types
53 |
54 | - name: 📐 Check formatting
55 | run: make py-check-format
56 |
--------------------------------------------------------------------------------
/pkg-r/DESCRIPTION:
--------------------------------------------------------------------------------
1 | Package: querychat
2 | Title: Filter and Query Data Frames in 'shiny' Using an LLM Chat Interface
3 | Version: 0.1.0.9000
4 | Authors@R: c(
5 | person("Garrick", "Aden-Buie", , "garrick@posit.co", role = c("aut", "cre"),
6 | comment = c(ORCID = "0000-0002-7111-0077")),
7 | person("Joe", "Cheng", , "joe@posit.co", role = c("aut", "ccp")),
8 | person("Carson", "Sievert", , "carson@posit.co", role = "aut",
9 | comment = c(ORCID = "0000-0002-4958-2844")),
10 | person("Posit Software, PBC", role = c("cph", "fnd"))
11 | )
12 | Description: Adds an LLM-powered chatbot to your 'shiny' app, that can
13 | turn your users' natural language questions into SQL queries that run
14 | against your data, and return the result as a reactive dataframe. Use
15 | it to drive reactive calculations, visualizations, downloads, etc.
16 | License: MIT + file LICENSE
17 | URL: https://posit-dev.github.io/querychat/pkg-r,
18 | https://posit-dev.github.io/querychat,
19 | https://github.com/posit-dev/querychat
20 | BugReports: https://github.com/posit-dev/querychat/issues
21 | Depends:
22 | R (>= 4.1.0)
23 | Imports:
24 | bslib,
25 | cli,
26 | DBI,
27 | duckdb,
28 | ellmer (>= 0.3.0),
29 | htmltools,
30 | lifecycle,
31 | promises,
32 | R6,
33 | rlang (>= 1.1.0),
34 | S7,
35 | shiny,
36 | shinychat (>= 0.2.0.9000),
37 | utils,
38 | whisker
39 | Suggests:
40 | bsicons,
41 | DT,
42 | palmerpenguins,
43 | RSQLite,
44 | shinytest2,
45 | testthat (>= 3.0.0),
46 | withr
47 | Remotes:
48 | posit-dev/shinychat/pkg-r
49 | Config/testthat/edition: 3
50 | Config/testthat/parallel: true
51 | Encoding: UTF-8
52 | Roxygen: list(markdown = TRUE)
53 | RoxygenNote: 7.3.3
54 |
--------------------------------------------------------------------------------
/pkg-py/tests/test_querychat.py:
--------------------------------------------------------------------------------
1 | import os
2 |
3 | import pandas as pd
4 | import pytest
5 | from querychat import QueryChat
6 |
7 |
8 | @pytest.fixture(autouse=True)
9 | def set_dummy_api_key():
10 | """Set a dummy OpenAI API key for testing."""
11 | old_api_key = os.environ.get("OPENAI_API_KEY")
12 | os.environ["OPENAI_API_KEY"] = "sk-dummy-api-key-for-testing"
13 | yield
14 | if old_api_key is not None:
15 | os.environ["OPENAI_API_KEY"] = old_api_key
16 | else:
17 | del os.environ["OPENAI_API_KEY"]
18 |
19 |
20 | @pytest.fixture
21 | def sample_df():
22 | """Create a sample pandas DataFrame for testing."""
23 | return pd.DataFrame(
24 | {
25 | "id": [1, 2, 3],
26 | "name": ["Alice", "Bob", "Charlie"],
27 | "age": [25, 30, 35],
28 | },
29 | )
30 |
31 |
32 | def test_querychat_init(sample_df):
33 | """Test that QueryChat (Express mode) initializes correctly."""
34 | qc = QueryChat(
35 | data_source=sample_df,
36 | table_name="test_table",
37 | greeting="Hello!",
38 | )
39 |
40 | # Verify basic attributes are set
41 | assert qc is not None
42 | assert qc.id == "test_table"
43 |
44 | # Even without server initialization, we should be able to query the data source
45 | result = qc.data_source.execute_query(
46 | "SELECT * FROM test_table WHERE id = 2",
47 | )
48 |
49 | assert len(result) == 1
50 | assert result.iloc[0]["name"] == "Bob"
51 |
52 |
53 | def test_querychat_custom_id(sample_df):
54 | """Test that QueryChat accepts custom ID."""
55 | qc = QueryChat(
56 | data_source=sample_df,
57 | table_name="test_table",
58 | id="custom_id",
59 | greeting="Hello!",
60 | )
61 |
62 | assert qc.id == "custom_id"
63 |
--------------------------------------------------------------------------------
/pkg-r/tests/testthat/apps/basic/app.R:
--------------------------------------------------------------------------------
1 | library(shiny)
2 | library(bslib, warn.conflicts = FALSE)
3 | library(querychat)
4 | library(DBI)
5 | library(RSQLite)
6 |
7 | # Mock chat function to avoid LLM API calls
8 | MockChat <- R6::R6Class(
9 | "MockChat",
10 | inherit = asNamespace("ellmer")[["Chat"]],
11 | public = list(
12 | stream_async = function(message, ...) {
13 | "Welcome! This is a mock response for testing."
14 | }
15 | )
16 | )
17 |
18 | # Create test database
19 | temp_db <- tempfile(fileext = ".db")
20 | conn <- dbConnect(RSQLite::SQLite(), temp_db)
21 | dbWriteTable(conn, "iris", iris, overwrite = TRUE)
22 | dbDisconnect(conn)
23 |
24 | # Setup database source and QueryChat instance
25 | db_conn <- dbConnect(RSQLite::SQLite(), temp_db)
26 |
27 | # Create QueryChat instance
28 | qc <- QueryChat$new(
29 | data_source = db_conn,
30 | table_name = "iris",
31 | greeting = "Welcome to the test app!",
32 | client = MockChat$new(ellmer::Provider("test", "test", "test"))
33 | )
34 |
35 | ui <- page_sidebar(
36 | title = "Test Database App",
37 | sidebar = qc$sidebar(),
38 | h2("Data"),
39 | DT::DTOutput("data_table"),
40 | h3("SQL Query"),
41 | verbatimTextOutput("sql_query")
42 | )
43 |
44 | server <- function(input, output, session) {
45 | qc_vals <- qc$server()
46 |
47 | output$data_table <- DT::renderDT(
48 | {
49 | qc_vals$df()
50 | },
51 | options = list(pageLength = 5)
52 | )
53 |
54 | output$sql_query <- renderText({
55 | query <- qc_vals$sql()
56 | if (is.null(query) || !nzchar(query)) "No filter applied" else query
57 | })
58 |
59 | session$onSessionEnded(function() {
60 | if (DBI::dbIsValid(db_conn)) {
61 | DBI::dbDisconnect(db_conn)
62 | }
63 | unlink(temp_db)
64 | })
65 | }
66 |
67 | shinyApp(ui = ui, server = server)
68 |
--------------------------------------------------------------------------------
/.github/workflows/docs-r-pkgdown.yml:
--------------------------------------------------------------------------------
1 | # Workflow derived from https://github.com/posit-dev/shinychat/blob/main/.github/workflows/pkgdown.yaml
2 | # Need help debugging build failures? Start at https://github.com/r-lib/actions#where-to-find-help
3 | on:
4 | push:
5 | branches: [main, master]
6 | paths:
7 | - 'pkg-r/man/**/*'
8 | - 'pkg-r/vignettes/**/*'
9 | - 'pkg-r/pkgdown/**/*'
10 | - '.github/workflows/docs-r-pkgdown.yml'
11 | pull_request:
12 | paths:
13 | - 'pkg-r/man/**/*'
14 | - 'pkg-r/vignettes/**/*'
15 | - 'pkg-r/pkgdown/**/*'
16 | - '.github/workflows/docs-r-pkgdown.yml'
17 | release:
18 | types: [published]
19 | workflow_dispatch:
20 |
21 | name: docs-r-pkgdown.yml
22 |
23 | permissions:
24 | contents: write
25 |
26 | jobs:
27 | r-docs-pkgdown:
28 | runs-on: ubuntu-latest
29 | # Only restrict concurrency for non-PR jobs
30 | concurrency:
31 | group: pkgdown-${{ github.event_name != 'pull_request' || github.run_id }}
32 | env:
33 | GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
34 | permissions:
35 | contents: write
36 |
37 | # Only run on release events for tags start with "r/v*"
38 | if: github.event_name != 'release' || startsWith(github.ref, 'refs/tags/r/v')
39 |
40 | steps:
41 | - uses: actions/checkout@v4
42 |
43 | - uses: r-lib/actions/setup-pandoc@v2
44 |
45 | - uses: r-lib/actions/setup-r@v2
46 | with:
47 | use-public-rspm: true
48 |
49 | - uses: r-lib/actions/setup-r-dependencies@v2
50 | with:
51 | extra-packages: any::pkgdown, local::.
52 | needs: website
53 | working-directory: pkg-r
54 |
55 | - name: Build site
56 | run: make r-docs
57 |
58 | - name: Deploy to GitHub pages 🚀
59 | if: github.event_name != 'pull_request'
60 | uses: JamesIves/github-pages-deploy-action@v4.5.0
61 | with:
62 | clean: false
63 | branch: gh-pages
64 | folder: docs
65 |
--------------------------------------------------------------------------------
/docs/logo-r.svg:
--------------------------------------------------------------------------------
1 |
15 |
--------------------------------------------------------------------------------
/pkg-r/tests/testthat/_snaps/QueryChat.md:
--------------------------------------------------------------------------------
1 | # QueryChat$new() / errors with invalid argument types
2 |
3 | Code
4 | QueryChat$new(test_df, table_name = "test", id = 123)
5 | Condition
6 | Error in `initialize()`:
7 | ! `id` must be a single string or `NULL`, not the number 123.
8 |
9 | ---
10 |
11 | Code
12 | QueryChat$new(test_df, table_name = "test", greeting = 123)
13 | Condition
14 | Error in `initialize()`:
15 | ! `greeting` must be a single string or `NULL`, not the number 123.
16 |
17 | ---
18 |
19 | Code
20 | QueryChat$new(test_df, table_name = "test", categorical_threshold = "not_a_number")
21 | Condition
22 | Error in `initialize()`:
23 | ! `categorical_threshold` must be a whole number, not the string "not_a_number".
24 |
25 | ---
26 |
27 | Code
28 | QueryChat$new(test_df, table_name = "test", cleanup = "not_logical")
29 | Condition
30 | Error in `initialize()`:
31 | ! `cleanup` must be `TRUE`, `FALSE`, or `NA`, not the string "not_logical".
32 |
33 | # QueryChat$server() errors when called outside Shiny context
34 |
35 | Code
36 | qc$server()
37 | Condition
38 | Error in `qc$server()`:
39 | ! `$server()` must be called within a Shiny server function
40 |
41 | # normalize_data_source() / errors with invalid data source types
42 |
43 | Code
44 | normalize_data_source("not_a_data_source", "table_name")
45 | Condition
46 | Error in `normalize_data_source()`:
47 | ! `data_source` must be a }}\preformatted{library(querychat)
18 |
19 | # Create a QueryChat object (table name inferred from variable)
20 | qc <- QueryChat$new(mtcars)
21 |
22 | # Option 1: Run a complete app with sensible defaults
23 | qc$app()
24 |
25 | # Option 2: Build a custom Shiny app
26 | ui <- page_sidebar(
27 | qc$sidebar(),
28 | dataTableOutput("data")
29 | )
30 |
31 | server <- function(input, output, session) \{
32 | qc$server()
33 | output$data <- renderDataTable(qc$df())
34 | \}
35 |
36 | shinyApp(ui, server)
37 | }\if{html}{\out{
}}
38 | }
39 |
40 | \section{Key Features}{
41 |
42 | \itemize{
43 | \item \strong{Natural language queries}: Ask questions in plain English
44 | \item \strong{SQL transparency}: See the generated SQL queries
45 | \item \strong{Multiple data sources}: Works with data frames and database connections
46 | \item \strong{Customizable}: Add data descriptions, extra instructions, and custom greetings
47 | \item \strong{LLM agnostic}: Works with OpenAI, Anthropic, Google, and other providers via ellmer
48 | }
49 | }
50 |
51 | \section{Main Components}{
52 |
53 | \itemize{
54 | \item \link{QueryChat}: The main R6 class for creating chat interfaces
55 | \item \link{DataSource}, \link{DataFrameSource}, \link{DBISource}: R6 classes for data sources
56 | }
57 | }
58 |
59 | \section{Examples}{
60 |
61 | To see examples included with the package, run:
62 |
63 | \if{html}{\out{}}\preformatted{shiny::runExample(package = "querychat")
64 | }\if{html}{\out{
}}
65 |
66 | This provides a list of available examples. To run a specific example, like
67 | '01-hello-app', use:
68 |
69 | \if{html}{\out{}}\preformatted{shiny::runExample("01-hello-app", package = "querychat")
70 | }\if{html}{\out{
}}
71 | }
72 |
73 | \seealso{
74 | Useful links:
75 | \itemize{
76 | \item \url{https://posit-dev.github.io/querychat/pkg-r}
77 | \item \url{https://posit-dev.github.io/querychat}
78 | }
79 |
80 | }
81 | \author{
82 | \strong{Maintainer}: Joe Cheng \email{joe@posit.co}
83 |
84 | Other contributors:
85 | \itemize{
86 | \item Posit Software, PBC [copyright holder, funder]
87 | }
88 |
89 | }
90 | \keyword{internal}
91 |
--------------------------------------------------------------------------------
/pkg-py/docs/greet.qmd:
--------------------------------------------------------------------------------
1 |
2 | ---
3 | title: Greet users
4 | ---
5 |
6 | ### Provide a greeting
7 |
8 | When the querychat UI first appears, you will usually want it to greet the user with some basic instructions. By default, these instructions are auto-generated every time a user arrives. In a production setting with multiple users/visitors, this is slow, wasteful, and non-deterministic. Instead, you should create a greeting file and pass it when creating your `QueryChat` object:
9 |
10 | ```{.python filename="titanic-app.py"}
11 | from querychat import QueryChat
12 | from querychat.data import titanic
13 | from pathlib import Path
14 |
15 | app_dir = Path(__file__).parent
16 |
17 | qc = QueryChat(titanic(), "titanic", greeting=app_dir / "greeting.md")
18 | app = qc.app()
19 | ```
20 |
21 | You can provide suggestions to the user by using the ` ` tag:
22 |
23 | ```markdown
24 | * **Filter and sort the data:**
25 | * Show only survivors
26 | * Filter to first class passengers under 30
27 | * Sort by fare from highest to lowest
28 |
29 | * **Answer questions about the data:**
30 | * What was the survival rate by gender?
31 | * What's the average age of children who survived?
32 | * How many passengers were traveling alone?
33 | ```
34 |
35 | These suggestions appear in the greeting and automatically populate the chat text box when clicked.
36 | You can see this behavior in our [`querychat template`](https://shiny.posit.co/py/templates/querychat/).
37 |
38 | ### Generate a greeting
39 |
40 | If you need help coming up with a greeting, you can use the `.generate_greeting()` method:
41 |
42 | ```{.python filename="penguins-greeting.py"}
43 | from palmerpenguins import load_penguins
44 | from querychat import QueryChat
45 | from pathlib import Path
46 |
47 | # Create QueryChat object with your dataset
48 | qc = QueryChat(load_penguins(), "penguins")
49 |
50 | # Generate a greeting (this calls the LLM)
51 | greeting_text = qc.generate_greeting()
52 | #> Hello! I'm here to help you explore and analyze the penguins dataset.
53 | #> Here are some example prompts you can try:
54 | #> ...
55 |
56 | # Save it for reuse
57 | with open("penguins_greeting.md", "w") as f:
58 | f.write(greeting_text)
59 | ```
60 |
61 | This approach generates a greeting once and saves it for reuse, avoiding the latency and cost of generating it for every user.
62 |
63 | ```{.python filename="penguins-app.py"}
64 | from palmerpenguins import load_penguins
65 | from querychat import QueryChat
66 | from pathlib import Path
67 |
68 | # Then use the saved greeting in your app
69 | app_dir = Path(__file__).parent
70 | qc = QueryChat(
71 | load_penguins(),
72 | "penguins",
73 | greeting=app_dir / "penguins_greeting.md",
74 | )
75 | app = qc.app()
76 | ```
77 |
--------------------------------------------------------------------------------
/pkg-r/inst/examples-shiny/02-sidebar-app/app.R:
--------------------------------------------------------------------------------
1 | library(shiny)
2 | library(bslib)
3 | library(querychat)
4 | library(palmerpenguins)
5 |
6 | # Define a custom greeting for the penguins app
7 | greeting <- r"(
8 | # Welcome to the Palmer Penguins Explorer! 🐧
9 |
10 | I can help you explore and analyze the Palmer Penguins dataset. Ask me questions
11 | about the penguins, and I'll generate SQL queries to get the answers.
12 |
13 | Try asking:
14 | - Show me the first 10 rows of the penguins dataset
15 | - What's the average bill length by species?
16 | - Which species has the largest body mass?
17 | - Create a summary of measurements grouped by species and island
18 | )"
19 |
20 | # Create QueryChat object with custom options
21 | qc <- QueryChat$new(
22 | penguins,
23 | greeting = greeting,
24 | data_description = paste(
25 | "The Palmer Penguins dataset contains measurements of bill",
26 | "dimensions, flipper length, body mass, sex, and species",
27 | "(Adelie, Chinstrap, and Gentoo) collected from three islands in",
28 | "the Palmer Archipelago, Antarctica."
29 | ),
30 | extra_instructions = paste(
31 | "When showing results, always explain what the data represents",
32 | "and highlight any interesting patterns you observe."
33 | )
34 | )
35 |
36 | # Define custom UI with sidebar
37 | ui <- page_sidebar(
38 | title = "Palmer Penguins Chat Explorer",
39 | sidebar = qc$sidebar(),
40 |
41 | card(
42 | fill = FALSE,
43 | card_header("Current SQL Query"),
44 | verbatimTextOutput("sql_query")
45 | ),
46 |
47 | card(
48 | full_screen = TRUE,
49 | card_header(
50 | "Current Data View",
51 | tooltip(
52 | bsicons::bs_icon("question-circle-fill", class = "mx-1"),
53 | "The table below shows the current filtered data based on your chat queries"
54 | ),
55 | tooltip(
56 | bsicons::bs_icon("info-circle-fill"),
57 | "The penguins dataset contains measurements on 344 penguins."
58 | )
59 | ),
60 | DT::DTOutput("data_table"),
61 | card_footer(
62 | markdown(
63 | "Data source: [palmerpenguins package](https://allisonhorst.github.io/palmerpenguins/)"
64 | )
65 | )
66 | )
67 | )
68 |
69 | # Define server logic
70 | server <- function(input, output, session) {
71 | # Initialize QueryChat server
72 | qc_vals <- qc$server()
73 |
74 | # Render the data table
75 | output$data_table <- DT::renderDT(
76 | {
77 | qc_vals$df()
78 | },
79 | fillContainer = TRUE,
80 | options = list(pageLength = 25, scrollX = TRUE)
81 | )
82 |
83 | # Render the SQL query
84 | output$sql_query <- renderText({
85 | query <- qc_vals$sql()
86 | if (is.null(query) || !nzchar(query)) {
87 | "No filter applied - showing all data"
88 | } else {
89 | query
90 | }
91 | })
92 | }
93 |
94 | shinyApp(ui = ui, server = server)
95 |
--------------------------------------------------------------------------------
/pkg-py/tests/test_init_with_pandas.py:
--------------------------------------------------------------------------------
1 | import os
2 |
3 | import narwhals.stable.v1 as nw
4 | import pandas as pd
5 | import pytest
6 | from querychat import QueryChat
7 |
8 |
9 | @pytest.fixture(autouse=True)
10 | def set_dummy_api_key():
11 | """Set a dummy OpenAI API key for testing."""
12 | old_api_key = os.environ.get("OPENAI_API_KEY")
13 | os.environ["OPENAI_API_KEY"] = "sk-dummy-api-key-for-testing"
14 | yield
15 | if old_api_key is not None:
16 | os.environ["OPENAI_API_KEY"] = old_api_key
17 | else:
18 | del os.environ["OPENAI_API_KEY"]
19 |
20 |
21 | def test_init_with_pandas_dataframe():
22 | """Test that QueryChat() can accept a pandas DataFrame."""
23 | # Create a simple pandas DataFrame
24 | df = pd.DataFrame(
25 | {
26 | "id": [1, 2, 3],
27 | "name": ["Alice", "Bob", "Charlie"],
28 | "age": [25, 30, 35],
29 | },
30 | )
31 |
32 | # Call QueryChat with the pandas DataFrame - it should not raise errors
33 | # The function should accept a pandas DataFrame even with the narwhals import change
34 | qc = QueryChat(
35 | data_source=df,
36 | table_name="test_table",
37 | greeting="hello!",
38 | )
39 |
40 | # Verify the result is properly configured
41 | assert qc is not None
42 |
43 |
44 | def test_init_with_narwhals_dataframe():
45 | """Test that QueryChat() can accept a narwhals DataFrame."""
46 | # Create a pandas DataFrame and convert to narwhals
47 | pdf = pd.DataFrame(
48 | {
49 | "id": [1, 2, 3],
50 | "name": ["Alice", "Bob", "Charlie"],
51 | "age": [25, 30, 35],
52 | },
53 | )
54 | nw_df = nw.from_native(pdf)
55 |
56 | # Call QueryChat with the narwhals DataFrame - it should not raise errors
57 | qc = QueryChat(
58 | data_source=nw_df,
59 | table_name="test_table",
60 | greeting="hello!",
61 | )
62 |
63 | # Verify the result is correctly configured
64 | assert qc is not None
65 |
66 |
67 | def test_init_with_narwhals_lazyframe_direct_query():
68 | """Test that QueryChat() can accept a narwhals LazyFrame and execute queries."""
69 | # Create a pandas DataFrame and convert to narwhals LazyFrame
70 | pdf = pd.DataFrame(
71 | {
72 | "id": [1, 2, 3],
73 | "name": ["Alice", "Bob", "Charlie"],
74 | "age": [25, 30, 35],
75 | },
76 | )
77 | nw_lazy = nw.from_native(pdf).lazy()
78 |
79 | # Call QueryChat with the narwhals LazyFrame
80 | qc = QueryChat(
81 | data_source=nw_lazy, # TODO(@gadebuie): Fix this type error
82 | table_name="test_table",
83 | greeting="hello!",
84 | )
85 |
86 | # Verify the result is correctly configured
87 | assert qc is not None
88 | assert hasattr(qc, "data_source")
89 |
90 | # Test that we can run a query on the data source
91 | query_result = qc.data_source.execute_query(
92 | "SELECT * FROM test_table WHERE id = 2",
93 | )
94 | assert len(query_result) == 1
95 | assert query_result.iloc[0]["name"] == "Bob"
96 |
--------------------------------------------------------------------------------
/pkg-r/inst/examples-shiny/sqlite/README.md:
--------------------------------------------------------------------------------
1 | # Database Setup Examples for querychat
2 |
3 | This document provides examples of how to set up querychat with various database types.
4 |
5 | ## SQLite
6 |
7 | ```r
8 | library(DBI)
9 | library(RSQLite)
10 | library(querychat)
11 |
12 | # Connect to SQLite database
13 | conn <- dbConnect(RSQLite::SQLite(), "path/to/your/database.db")
14 |
15 | # Create QueryChat instance
16 | qc <- QueryChat$new(
17 | conn,
18 | "your_table_name",
19 | greeting = "Welcome! Ask me about your data.",
20 | data_description = "Description of your data..."
21 | )
22 |
23 | # Launch the app
24 | qc$app()
25 | ```
26 |
27 | ## PostgreSQL
28 |
29 | ```r
30 | library(DBI)
31 | library(RPostgreSQL) # or library(RPostgres)
32 | library(querychat)
33 |
34 | # Connect to PostgreSQL
35 | conn <- dbConnect(
36 | RPostgreSQL::PostgreSQL(), # or RPostgres::Postgres()
37 | dbname = "your_database",
38 | host = "localhost",
39 | port = 5432,
40 | user = "your_username",
41 | password = "your_password"
42 | )
43 |
44 | # Create QueryChat instance
45 | qc <- QueryChat$new(conn, "your_table_name")
46 |
47 | # Launch the app
48 | qc$app()
49 | ```
50 |
51 | ## MySQL
52 |
53 | ```r
54 | library(DBI)
55 | library(RMySQL)
56 | library(querychat)
57 |
58 | # Connect to MySQL
59 | conn <- dbConnect(
60 | RMySQL::MySQL(),
61 | dbname = "your_database",
62 | host = "localhost",
63 | user = "your_username",
64 | password = "your_password"
65 | )
66 |
67 | # Create QueryChat instance
68 | qc <- QueryChat$new(conn, "your_table_name")
69 |
70 | # Launch the app
71 | qc$app()
72 | ```
73 |
74 | ## Connection Management
75 |
76 | When using database sources in custom Shiny apps, make sure to properly manage connections:
77 |
78 | ```r
79 | server <- function(input, output, session) {
80 | # Initialize QueryChat server
81 | qc$server()
82 |
83 | # Your custom outputs here
84 | output$table <- renderTable(qc$df())
85 |
86 | # Clean up connection when session ends
87 | session$onSessionEnded(function() {
88 | if (dbIsValid(conn)) {
89 | dbDisconnect(conn)
90 | }
91 | })
92 | }
93 | ```
94 |
95 | ## Security Considerations
96 |
97 | - Only SELECT queries are allowed - no INSERT, UPDATE, or DELETE operations
98 | - All SQL queries are visible to users for transparency
99 | - Use appropriate database user permissions (read-only recommended)
100 | - Consider connection pooling for production applications
101 | - Validate that users only have access to intended tables
102 |
103 | ## Error Handling
104 |
105 | The database source implementation includes robust error handling:
106 |
107 | - Validates table existence during creation
108 | - Handles database connection issues gracefully
109 | - Provides informative error messages for invalid queries
110 | - Falls back gracefully when statistical queries fail
111 |
112 | ## Performance Tips
113 |
114 | - Use appropriate database indexes for columns commonly used in queries
115 | - Consider limiting row counts for very large tables
116 | - Database connections are reused for better performance
117 | - Schema information is cached to avoid repeated metadata queries
--------------------------------------------------------------------------------
/.claude/R-TESTING.md:
--------------------------------------------------------------------------------
1 | # R Testing Guide
2 |
3 | ## Test Organization
4 |
5 | Use testthat 3rd-edition style tests. For tests covering a single behavior, use standard `test_that()` style. For testing classes, methods and functions, use **BDD style** with `describe()` and `it()` blocks.
6 |
7 | Test files should be placed in `pkg-r/tests/testthat/`. Test file names should directly match the R source file, e.g. `R/{name}.R` --> `tests/testthat/test-{name}.R`.
8 |
9 | ### Key BDD Principles
10 |
11 | 1. **Flat structure**: No nested `describe()` blocks
12 | 2. **Group by method/function**: One `describe()` block per method or function being tested
13 | 3. **Shared fixtures**: Set up at the top of `describe()` blocks, not inside `it()` blocks, when possible
14 | 4. **Self-contained tests**: Each `it()` block should be runnable independently after running the shared setup
15 | 5. Only use `describe()` blocks for grouped behavior-oriented tests. Use `test_that()` for single or unit tests
16 |
17 | ### Describe Block Structure
18 |
19 | ```r
20 | describe("ClassName$method()", {
21 | # Shared fixtures here
22 | test_data <- new_test_df()
23 |
24 | it("describes what the method does", {
25 | # Test implementation
26 | })
27 | })
28 | ```
29 |
30 | ## Fixture Helpers
31 |
32 | Common test fixtures are stored in `pkg-r/tests/testthat/helper-fixtures.R`.
33 |
34 | ### Usage Pattern
35 |
36 | ```r
37 | describe("DataSource$execute_query()", {
38 | # Shared fixture at top
39 | test_df <- new_test_df()
40 | df_source <- local_data_frame_source(test_df)
41 |
42 | it("executes basic queries", {
43 | result <- df_source$execute_query("SELECT * FROM test_table")
44 | expect_s3_class(result, "data.frame")
45 | })
46 | })
47 | ```
48 |
49 | ## Cleanup
50 |
51 | - Use `withr::defer()` for cleanup when not using local_* helpers
52 | - Use `withr::local_*` functions for temporary state (options, envvars, files)
53 | - The fixture helpers handle cleanup automatically via `withr::defer()`
54 |
55 | ## Test Descriptions
56 |
57 | - `describe()`: Use method/function names like `"ClassName$method()"` or `"function_name()"`
58 | - `it()`: Describe behavior at the right level - what does it do, not how
59 | - Group related assertions in a single `it()` block rather than splitting into many small tests
60 |
61 | ### Good Examples
62 |
63 | ```r
64 | describe("querychat_tool_starts_open()", {
65 | it("uses the tool default when options are unset", {
66 | withr::local_options(querychat.tool_details = NULL)
67 |
68 | expect_true(querychat_tool_starts_open("query"))
69 | expect_true(querychat_tool_starts_open("update"))
70 | expect_false(querychat_tool_starts_open("reset"))
71 | })
72 | })
73 | ```
74 |
75 | ## Common patterns
76 |
77 | ### Testing Errors
78 |
79 | Prefer snapshot testing around expected errors so that the error message is captured in the snapshot.
80 |
81 | ```r
82 | # Don't do this
83 | expect_error(foo_will_error())
84 |
85 | # Do this
86 | expect_snapshot(error = TRUE, foo_will_error())
87 | ```
88 |
89 | ## Running Tests
90 |
91 | ```bash
92 | # All tests (from repo root)
93 | make r-check-tests
94 |
95 | # Single file (e.g. to test tests/testthat/test-data-source.R)
96 | testthat::test(filter = "data-source", reporter = "check")
97 | ```
98 |
--------------------------------------------------------------------------------
/pkg-r/inst/examples-shiny/sqlite/app.R:
--------------------------------------------------------------------------------
1 | library(shiny)
2 | library(bslib)
3 | library(querychat)
4 | library(DBI)
5 | library(RSQLite)
6 | library(palmerpenguins)
7 |
8 | # Create a sample SQLite database for demonstration
9 | # In a real app, you would connect to your existing database
10 | temp_db <- tempfile(fileext = ".db")
11 | onStop(function() {
12 | if (file.exists(temp_db)) {
13 | unlink(temp_db)
14 | }
15 | })
16 |
17 | conn <- dbConnect(RSQLite::SQLite(), temp_db)
18 |
19 | # Create sample data in the database
20 | dbWriteTable(conn, "penguins", palmerpenguins::penguins, overwrite = TRUE)
21 |
22 | # Define a custom greeting for the database app
23 | greeting <- "
24 | # Welcome to the Database Query Assistant! 🐧
25 |
26 | I can help you explore and analyze the Palmer Penguins dataset from the connected database.
27 | Ask me questions about the penguins, and I'll generate SQL queries to get the answers.
28 |
29 | Try asking:
30 | - Show me the first 10 rows of the penguins dataset
31 | - What's the average bill length by species?
32 | - Which species has the largest body mass?
33 | - Create a summary of measurements grouped by species and island
34 | "
35 |
36 | # Create QueryChat object with database connection
37 | qc <- QueryChat$new(
38 | conn,
39 | "penguins",
40 | greeting = greeting,
41 | data_description = "This database contains the Palmer Penguins dataset with measurements of bill dimensions, flipper length, body mass, sex, and species (Adelie, Chinstrap, and Gentoo) collected from three islands in the Palmer Archipelago, Antarctica.",
42 | extra_instructions = "When showing results, always explain what the data represents and highlight any interesting patterns you observe."
43 | )
44 |
45 | ui <- page_sidebar(
46 | title = "Database Query Chat",
47 | sidebar = qc$sidebar(),
48 |
49 | card(
50 | fill = FALSE,
51 | card_header("Current SQL Query"),
52 | verbatimTextOutput("sql_query")
53 | ),
54 |
55 | card(
56 | full_screen = TRUE,
57 | card_header(
58 | "Current Data View",
59 | tooltip(
60 | bsicons::bs_icon("question-circle-fill", class = "mx-1"),
61 | "The table below shows the current filtered data based on your chat queries"
62 | ),
63 | tooltip(
64 | bsicons::bs_icon("info-circle-fill"),
65 | "The penguins dataset contains measurements on 344 penguins."
66 | )
67 | ),
68 | DT::DTOutput("data_table"),
69 | card_footer(
70 | markdown(
71 | "Data source: [palmerpenguins package](https://allisonhorst.github.io/palmerpenguins/)"
72 | )
73 | )
74 | )
75 | )
76 |
77 | server <- function(input, output, session) {
78 | qc_vals <- qc$server()
79 |
80 | output$data_table <- DT::renderDT(
81 | {
82 | qc_vals$df()
83 | },
84 | fillContainer = TRUE,
85 | options = list(pageLength = 10, scrollX = TRUE)
86 | )
87 |
88 | output$sql_query <- renderText({
89 | query <- qc_vals$sql()
90 | if (is.null(query) || !nzchar(query)) {
91 | "No filter applied - showing all data"
92 | } else {
93 | query
94 | }
95 | })
96 | }
97 |
98 | shinyApp(ui = ui, server = server)
99 |
--------------------------------------------------------------------------------
/pkg-py/src/querychat/_deprecated.py:
--------------------------------------------------------------------------------
1 | from __future__ import annotations
2 |
3 | from typing import TYPE_CHECKING, Any, Optional, Union
4 |
5 | from shiny import Inputs, Outputs, Session, module, ui
6 |
7 | if TYPE_CHECKING:
8 | from pathlib import Path
9 |
10 | import chatlas
11 | import sqlalchemy
12 | from narwhals.stable.v1.typing import IntoFrame
13 |
14 | from ._datasource import DataSource
15 |
16 |
17 | def init(
18 | data_source: IntoFrame | sqlalchemy.Engine,
19 | table_name: str,
20 | *,
21 | greeting: Optional[str | Path] = None,
22 | data_description: Optional[str | Path] = None,
23 | extra_instructions: Optional[str | Path] = None,
24 | prompt_template: Optional[str | Path] = None,
25 | system_prompt_override: Optional[str] = None,
26 | client: Optional[Union[chatlas.Chat, str]] = None,
27 | ):
28 | """
29 | Initialize querychat with any compliant data source.
30 |
31 | **Deprecated.** Use `QueryChat()` instead.
32 | """
33 | raise RuntimeError("init() is deprecated. Use QueryChat() instead.")
34 |
35 |
36 | @module.ui
37 | def mod_ui(**kwargs) -> ui.TagList:
38 | """
39 | Create the UI for the querychat component.
40 |
41 | **Deprecated.** Use `QueryChat.ui()` instead.
42 | """
43 | raise RuntimeError("mod_ui() is deprecated. Use QueryChat.ui() instead.")
44 |
45 |
46 | @module.server
47 | def mod_server(
48 | input: Inputs,
49 | output: Outputs,
50 | session: Session,
51 | querychat_config: Any,
52 | ):
53 | """
54 | Initialize the querychat server.
55 |
56 | **Deprecated.** Use `QueryChat.server()` instead.
57 | """
58 | raise RuntimeError("mod_server() is deprecated. Use QueryChat.server() instead.")
59 |
60 |
61 | def sidebar(
62 | id: str,
63 | width: int = 400,
64 | height: str = "100%",
65 | **kwargs,
66 | ) -> ui.Sidebar:
67 | """
68 | Create a sidebar containing the querychat UI.
69 |
70 | **Deprecated.** Use `QueryChat.sidebar()` instead.
71 | """
72 | raise RuntimeError("sidebar() is deprecated. Use QueryChat.sidebar() instead.")
73 |
74 |
75 | def system_prompt(
76 | data_source: DataSource,
77 | *,
78 | data_description: Optional[str | Path] = None,
79 | extra_instructions: Optional[str | Path] = None,
80 | categorical_threshold: int = 20,
81 | prompt_template: Optional[str | Path] = None,
82 | ) -> str:
83 | """
84 | Create a system prompt for the chat model based on a data source's schema
85 | and optional additional context and instructions.
86 |
87 | **Deprecated.** Use `QueryChat.set_system_prompt()` instead.
88 | """
89 | raise RuntimeError(
90 | "system_prompt() is deprecated. Use QueryChat.set_system_prompt() instead."
91 | )
92 |
93 |
94 | def greeting(
95 | querychat_config,
96 | *,
97 | generate: bool = True,
98 | stream: bool = False,
99 | **kwargs,
100 | ) -> str | None:
101 | """
102 | Generate or retrieve a greeting message.
103 |
104 | **Deprecated.** Use `QueryChat.generate_greeting()` instead.
105 | """
106 | raise RuntimeError(
107 | "greeting() is deprecated. Use QueryChat.generate_greeting() instead."
108 | )
109 |
--------------------------------------------------------------------------------
/pkg-r/NEWS.md:
--------------------------------------------------------------------------------
1 | # querychat (development version)
2 |
3 | * **Breaking change:** The `$sql()` method now returns `NULL` instead of `""` (empty string) when no query has been set, aligning with the behavior of `$title()` for consistency. Most code using `isTruthy()` or similar falsy checks will continue working without changes. Code that explicitly checks `sql() == ""` should be updated to use falsy checks (e.g., `!isTruthy(sql())`) or explicit null checks (`is.null(sql())`). (#146)
4 |
5 | * 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)
6 |
7 | * 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)
8 |
9 | * 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)
10 | * In addition, `querychat_data_source()` was renamed to `as_querychat_data_source()`, and remains exported for a developer extension point, but users no longer have to explicitly create a data source. (#109)
11 |
12 | * Added `prompt_template` support for `querychat_system_prompt()`. (Thank you, @oacar! #37, #45)
13 |
14 | * `querychat_init()` now accepts a `client`, replacing the previous `create_chat_func` argument. (#60)
15 |
16 | The `client` can be:
17 |
18 | * an `ellmer::Chat` object,
19 | * a function that returns an `ellmer::Chat` object,
20 | * or a provider-model string, e.g. `"openai/gpt-4.1"`, to be passed to `ellmer::chat()`.
21 |
22 | If `client` is not provided, querychat will use
23 |
24 | * the `querychat.client` R option, which can be any of the above options,
25 | * the `QUERYCHAT_CLIENT` environment variable, which should be a provider-model string,
26 | * or the default model from `ellmer::chat_openai()`.
27 |
28 | * `querychat_server()` now uses a `shiny::ExtendedTask` for streaming the chat response, which allows the dashboard to update and remain responsive while the chat response is streaming in. (#63)
29 |
30 | * querychat now requires `ellmer` version 0.3.0 or later and uses rich tool cards for dashboard updates and database queries. (#65)
31 |
32 | * New `querychat_app()` function lets you quickly launch a Shiny app with a querychat chat interface. (#66)
33 |
34 | * `querychat_ui()` now adds a `.querychat` class to the chat container and `querychat_sidebar()` adds a `.querychat-sidebar` class to the sidebar, allowing for easier customization via CSS. (#68)
35 |
36 | * querychat now uses a separate tool to reset the dashboard. (#80)
37 |
38 | * `querychat_greeting()` can be used to generate a greeting message for your querychat bot. (#87)
39 |
40 | * querychat's system prompt and tool descriptions were rewritten for clarity and future extensibility. (#90)
41 |
--------------------------------------------------------------------------------
/pkg-py/CHANGELOG.md:
--------------------------------------------------------------------------------
1 | # Changelog
2 |
3 | All notable changes to this project will be documented in this file.
4 |
5 | The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6 | and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7 |
8 | ## [UNRELEASED]
9 |
10 |
11 |
12 | ## [0.3.0] - 2025-12-10
13 |
14 | ### Breaking Changes
15 |
16 | * The entire functional API (i.e., `init()`, `sidebar()`, `server()`, etc) has been hard deprecated in favor of a simpler OOP-based API. Namely, the new `QueryChat()` class is now the main entry point (instead of `init()`) and has methods to replace old functions (e.g., `.sidebar()`, `.server()`, etc). (#101)
17 |
18 | * The `.sql()` method now returns `None` instead of `""` (empty string) when no query has been set, aligning with the behavior of `.title()` for consistency. Most code using the `or` operator or `req()` for falsy checks will continue working without changes. Code that explicitly checks `sql() == ""` should be updated to use falsy checks (`if not sql()`) or explicit null checks (`if sql() is None`). (#146)
19 |
20 | ### New features
21 |
22 | * New `QueryChat.app()` method enables quicker/easier chatting with a dataset. (#104)
23 |
24 | * 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)
25 |
26 | * The current SQL query and title can now be programmatically set through the `.sql()` and `.title()` methods of `QueryChat()`. (#98, #101)
27 |
28 | * New `querychat.data` module provides sample datasets (`titanic()` and `tips()`) to make it easier to get started without external dependencies. (#118)
29 |
30 | * Added a `.generate_greeting()` method to help you create a greeting message for your querychat bot. (#87)
31 |
32 | * Added `querychat_reset_dashboard()` tool for easily resetting the dashboard filters when asked by the user. (#81)
33 |
34 | ### Improvements
35 |
36 | * Added rich tool UI support using shinychat development version and chatlas >= 0.11.1. (#67)
37 |
38 | * querychat's system prompt and tool descriptions were rewritten for clarity and future extensibility. (#90)
39 |
40 | * 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)
41 |
42 | ## [0.2.2] - 2025-09-04
43 |
44 | * Fixed another issue with data sources that aren't already narwhals DataFrames (#83)
45 |
46 | ## [0.2.1] - 2025-09-04
47 |
48 | * Fixed an issue with the query tool when used with SQLAlchemy data sources. (@npelikan #79)
49 |
50 | ## [0.2.0] - 2025-09-02
51 |
52 | * `querychat.init()` now accepts a `client` argument, replacing the previous `create_chat_callback` argument. (#60)
53 |
54 | The `client` can be:
55 |
56 | * a `chatlas.Chat` object,
57 | * a function that returns a `chatlas.Chat` object,
58 | * or a provider-model string, e.g. `"openai/gpt-4.1"`, to be passed to `chatlas.ChatAuto()`.
59 |
60 | If `client` is not provided, querychat will use the `QUERYCHAT_CLIENT` environment variable, which should be a provider-model string. If the envvar is not set, querychat uses OpenAI with the default model from `chatlas.ChatOpenAI()`.
61 |
62 | * `querychat.ui()` now adds a `.querychat` class to the chat container and `querychat.sidebar()` adds a `.querychat-sidebar` class to the sidebar, allowing for easier customization via CSS. (#68)
63 |
64 | ## [0.1.0] - 2025-05-24
65 |
66 | This first release of the `querychat` package.
67 |
--------------------------------------------------------------------------------
/pkg-py/docs/_quarto.yml:
--------------------------------------------------------------------------------
1 | project:
2 | type: website
3 | output-dir: ../../docs/py
4 | pre-render:
5 | cp ../CHANGELOG.md CHANGELOG.md
6 |
7 | website:
8 | title: "querychat"
9 | site-url: https://posit-dev.github.io/querychat/py
10 | description: Explore data using natural language
11 | page-navigation: true
12 |
13 | bread-crumbs: true
14 | open-graph: true
15 | twitter-card: true
16 |
17 | repo-url: https://github.com/posit-dev/querychat/
18 | repo-actions: [issue, edit]
19 | repo-subdir: pkg-py/docs
20 |
21 | page-footer:
22 | left: |
23 | Proudly supported by
24 | [{fig-alt="Posit" width=65px}](https://posit.co)
25 |
26 | navbar:
27 | background: "#193D56"
28 | search: true
29 | title: 'QueryChat'
30 | #title: '
QueryChat'
31 |
32 | right:
33 | - text: API Reference
34 | href: reference/index.qmd
35 | - text: Changelog
36 | href: /CHANGELOG.html
37 | - icon: github
38 | href: https://github.com/posit-dev/querychat
39 | aria-label: GitHub repository
40 |
41 | sidebar:
42 | - id: get-started
43 | title: Get Started
44 | style: floating
45 | align: left
46 | contents:
47 | - index.qmd
48 | - section: "Overview"
49 | contents:
50 | - models.qmd
51 | - data-sources.qmd
52 | - context.qmd
53 | - build.qmd
54 | - greet.qmd
55 | - tools.qmd
56 |
57 |
58 | format:
59 | html:
60 | theme:
61 | - styles.scss
62 | toc: true
63 |
64 | lightbox: auto
65 |
66 | metadata-files:
67 | - reference/_sidebar.yml
68 |
69 | quartodoc:
70 | package: querychat
71 | render_interlinks: true
72 | sidebar: reference/_sidebar.yml
73 | css: reference/_styles-quartodoc.css
74 | sections:
75 | - title: The Querychat class
76 | desc: The starting point for any QueryChat session
77 | contents:
78 | - name: QueryChat
79 | include_inherited: true
80 | - name: express.QueryChat
81 | include_inherited: true
82 |
83 | - title: Reactive values
84 | desc: Session-specific reactive values representing the current query
85 | contents:
86 | - types.ServerValues
87 |
88 | - title: Data Sources
89 | desc: The underlying logic for managing data sources
90 | contents:
91 | - name: types.DataSource
92 | signature_name: short
93 | - name: types.DataFrameSource
94 | signature_name: short
95 | - name: types.SQLAlchemySource
96 | signature_name: short
97 |
98 | - title: Tools
99 | desc: The underlying tools provided to the LLM
100 | contents:
101 | - name: tools.tool_query
102 | signature_name: short
103 | - name: tools.tool_update_dashboard
104 | signature_name: short
105 | - name: tools.tool_reset_dashboard
106 | signature_name: short
107 |
108 | filters:
109 | - "interlinks"
110 |
111 | interlinks:
112 | fast: true
113 | sources:
114 | pydantic:
115 | url: https://docs.pydantic.dev/latest/
116 | python:
117 | url: https://docs.python.org/3/
118 |
119 | editor:
120 | render-on-save: true
121 | markdown:
122 | canonical: true
123 | wrap: sentence
124 |
--------------------------------------------------------------------------------
/pkg-py/tests/test_data.py:
--------------------------------------------------------------------------------
1 | """Tests for the querychat.data module."""
2 |
3 | import pandas as pd
4 | from querychat.data import tips, titanic
5 |
6 |
7 | def test_titanic_returns_dataframe():
8 | """Test that titanic() returns a pandas DataFrame."""
9 | df = titanic()
10 | assert isinstance(df, pd.DataFrame)
11 |
12 |
13 | def test_titanic_has_expected_shape():
14 | """Test that the Titanic dataset has the expected number of rows and columns."""
15 | df = titanic()
16 | assert df.shape == (891, 15), f"Expected (891, 15) but got {df.shape}"
17 |
18 |
19 | def test_titanic_has_expected_columns():
20 | """Test that the Titanic dataset has the expected column names."""
21 | df = titanic()
22 | expected_columns = [
23 | "survived",
24 | "pclass",
25 | "sex",
26 | "age",
27 | "sibsp",
28 | "parch",
29 | "fare",
30 | "embarked",
31 | "class",
32 | "who",
33 | "adult_male",
34 | "deck",
35 | "embark_town",
36 | "alive",
37 | "alone",
38 | ]
39 | assert list(df.columns) == expected_columns
40 |
41 |
42 | def test_titanic_data_integrity():
43 | """Test basic data integrity of the Titanic dataset."""
44 | df = titanic()
45 |
46 | # Check that survived column has only 0 and 1 values
47 | assert set(df["survived"].dropna().unique()) <= {0, 1}
48 |
49 | # Check that pclass has only 1, 2, 3
50 | assert set(df["pclass"].dropna().unique()) <= {1, 2, 3}
51 |
52 | # Check that sex has only 'male' and 'female'
53 | assert set(df["sex"].dropna().unique()) <= {"male", "female"}
54 |
55 | # Check that fare is non-negative
56 | assert (df["fare"].dropna() >= 0).all()
57 |
58 |
59 | def test_titanic_creates_new_copy():
60 | """Test that titanic() returns a new copy each time it's called."""
61 | df1 = titanic()
62 | df2 = titanic()
63 |
64 | # They should not be the same object
65 | assert df1 is not df2
66 |
67 | # But they should have the same data
68 | assert df1.equals(df2)
69 |
70 |
71 | def test_tips_returns_dataframe():
72 | """Test that tips() returns a pandas DataFrame."""
73 | df = tips()
74 | assert isinstance(df, pd.DataFrame)
75 |
76 |
77 | def test_tips_has_expected_shape():
78 | """Test that the tips dataset has the expected number of rows and columns."""
79 | df = tips()
80 | assert df.shape == (244, 7), f"Expected (244, 7) but got {df.shape}"
81 |
82 |
83 | def test_tips_has_expected_columns():
84 | """Test that the tips dataset has the expected column names."""
85 | df = tips()
86 | expected_columns = [
87 | "total_bill",
88 | "tip",
89 | "sex",
90 | "smoker",
91 | "day",
92 | "time",
93 | "size",
94 | ]
95 | assert list(df.columns) == expected_columns
96 |
97 |
98 | def test_tips_data_integrity():
99 | """Test basic data integrity of the tips dataset."""
100 | df = tips()
101 |
102 | # Check that total_bill is positive
103 | assert (df["total_bill"] > 0).all()
104 |
105 | # Check that tip is non-negative
106 | assert (df["tip"] >= 0).all()
107 |
108 | # Check that sex has only expected values
109 | assert set(df["sex"].dropna().unique()) <= {"Male", "Female"}
110 |
111 | # Check that smoker has only expected values
112 | assert set(df["smoker"].dropna().unique()) <= {"Yes", "No"}
113 |
114 | # Check that size is positive
115 | assert (df["size"] > 0).all()
116 |
117 |
118 | def test_tips_creates_new_copy():
119 | """Test that tips() returns a new copy each time it's called."""
120 | df1 = tips()
121 | df2 = tips()
122 |
123 | # They should not be the same object
124 | assert df1 is not df2
125 |
126 | # But they should have the same data
127 | assert df1.equals(df2)
128 |
--------------------------------------------------------------------------------
/pkg-py/tests/test_df_to_html.py:
--------------------------------------------------------------------------------
1 | import sqlite3
2 | import tempfile
3 | from pathlib import Path
4 |
5 | import pandas as pd
6 | import pytest
7 | from querychat._datasource import DataFrameSource, SQLAlchemySource
8 | from querychat._utils import df_to_html
9 | from sqlalchemy import create_engine
10 |
11 |
12 | @pytest.fixture
13 | def sample_dataframe():
14 | """Create a sample pandas DataFrame for testing."""
15 | return pd.DataFrame(
16 | {
17 | "id": [1, 2, 3, 4, 5],
18 | "name": ["Alice", "Bob", "Charlie", "Diana", "Eve"],
19 | "age": [25, 30, 35, 28, 32],
20 | "salary": [50000, 60000, 70000, 55000, 65000],
21 | },
22 | )
23 |
24 |
25 | @pytest.fixture
26 | def sample_sqlite():
27 | """Create a temporary SQLite database with test data."""
28 | temp_db = tempfile.NamedTemporaryFile(delete=False, suffix=".db") # noqa: SIM115
29 | temp_db.close()
30 |
31 | conn = sqlite3.connect(temp_db.name)
32 | cursor = conn.cursor()
33 |
34 | cursor.execute("""
35 | CREATE TABLE employees (
36 | id INTEGER PRIMARY KEY,
37 | name TEXT,
38 | age INTEGER,
39 | salary REAL
40 | )
41 | """)
42 |
43 | test_data = [
44 | (1, "Alice", 25, 50000),
45 | (2, "Bob", 30, 60000),
46 | (3, "Charlie", 35, 70000),
47 | (4, "Diana", 28, 55000),
48 | (5, "Eve", 32, 65000),
49 | ]
50 |
51 | cursor.executemany(
52 | "INSERT INTO employees (id, name, age, salary) VALUES (?, ?, ?, ?)",
53 | test_data,
54 | )
55 |
56 | conn.commit()
57 | conn.close()
58 |
59 | engine = create_engine(f"sqlite:///{temp_db.name}")
60 | yield engine
61 |
62 | # Cleanup
63 | Path(temp_db.name).unlink()
64 |
65 |
66 | def test_df_to_html_with_dataframe_source_result(sample_dataframe):
67 | """Test that df_to_html() works with results from DataFrameSource.execute_query()."""
68 | source = DataFrameSource(sample_dataframe, "employees")
69 |
70 | # Execute query to get pandas DataFrame
71 | result_df = source.execute_query("SELECT * FROM employees WHERE age > 25")
72 |
73 | # This should succeed after the fix
74 | html_output = df_to_html(result_df)
75 |
76 | # Verify the HTML contains expected content
77 | assert isinstance(html_output, str)
78 | assert "}}
14 | \describe{
15 | \item{\code{table_name}}{Name of the table to be used in SQL queries}
16 | }
17 | \if{html}{\out{
}}
18 | }
19 | \section{Methods}{
20 | \subsection{Public methods}{
21 | \itemize{
22 | \item \href{#method-DataSource-get_db_type}{\code{DataSource$get_db_type()}}
23 | \item \href{#method-DataSource-get_schema}{\code{DataSource$get_schema()}}
24 | \item \href{#method-DataSource-execute_query}{\code{DataSource$execute_query()}}
25 | \item \href{#method-DataSource-test_query}{\code{DataSource$test_query()}}
26 | \item \href{#method-DataSource-get_data}{\code{DataSource$get_data()}}
27 | \item \href{#method-DataSource-cleanup}{\code{DataSource$cleanup()}}
28 | \item \href{#method-DataSource-clone}{\code{DataSource$clone()}}
29 | }
30 | }
31 | \if{html}{\out{}} 32 | \if{html}{\out{}} 33 | \if{latex}{\out{\hypertarget{method-DataSource-get_db_type}{}}} 34 | \subsection{Method \code{get_db_type()}}{ 35 | Get the database type 36 | \subsection{Usage}{ 37 | \if{html}{\out{
}}\preformatted{DataSource$get_db_type()}\if{html}{\out{
}}
38 | }
39 |
40 | \subsection{Returns}{
41 | A string describing the database type (e.g., "DuckDB", "SQLite")
42 | }
43 | }
44 | \if{html}{\out{}} 45 | \if{html}{\out{}} 46 | \if{latex}{\out{\hypertarget{method-DataSource-get_schema}{}}} 47 | \subsection{Method \code{get_schema()}}{ 48 | Get schema information about the table 49 | \subsection{Usage}{ 50 | \if{html}{\out{
}}\preformatted{DataSource$get_schema(categorical_threshold = 20)}\if{html}{\out{
}}
51 | }
52 |
53 | \subsection{Arguments}{
54 | \if{html}{\out{}}
55 | \describe{
56 | \item{\code{categorical_threshold}}{Maximum number of unique values for a text
57 | column to be considered categorical}
58 | }
59 | \if{html}{\out{
}}
60 | }
61 | \subsection{Returns}{
62 | A string containing schema information formatted for LLM prompts
63 | }
64 | }
65 | \if{html}{\out{}} 66 | \if{html}{\out{}} 67 | \if{latex}{\out{\hypertarget{method-DataSource-execute_query}{}}} 68 | \subsection{Method \code{execute_query()}}{ 69 | Execute a SQL query and return results 70 | \subsection{Usage}{ 71 | \if{html}{\out{
}}\preformatted{DataSource$execute_query(query)}\if{html}{\out{
}}
72 | }
73 |
74 | \subsection{Arguments}{
75 | \if{html}{\out{}}
76 | \describe{
77 | \item{\code{query}}{SQL query string to execute}
78 | }
79 | \if{html}{\out{
}}
80 | }
81 | \subsection{Returns}{
82 | A data frame containing query results
83 | }
84 | }
85 | \if{html}{\out{}} 86 | \if{html}{\out{}} 87 | \if{latex}{\out{\hypertarget{method-DataSource-test_query}{}}} 88 | \subsection{Method \code{test_query()}}{ 89 | Test a SQL query by fetching only one row 90 | \subsection{Usage}{ 91 | \if{html}{\out{
}}\preformatted{DataSource$test_query(query)}\if{html}{\out{
}}
92 | }
93 |
94 | \subsection{Arguments}{
95 | \if{html}{\out{}}
96 | \describe{
97 | \item{\code{query}}{SQL query string to test}
98 | }
99 | \if{html}{\out{
}}
100 | }
101 | \subsection{Returns}{
102 | A data frame containing one row of results (or empty if no matches)
103 | }
104 | }
105 | \if{html}{\out{}} 106 | \if{html}{\out{}} 107 | \if{latex}{\out{\hypertarget{method-DataSource-get_data}{}}} 108 | \subsection{Method \code{get_data()}}{ 109 | Get the unfiltered data as a data frame 110 | \subsection{Usage}{ 111 | \if{html}{\out{
}}\preformatted{DataSource$get_data()}\if{html}{\out{
}}
112 | }
113 |
114 | \subsection{Returns}{
115 | A data frame containing all data from the table
116 | }
117 | }
118 | \if{html}{\out{}} 119 | \if{html}{\out{}} 120 | \if{latex}{\out{\hypertarget{method-DataSource-cleanup}{}}} 121 | \subsection{Method \code{cleanup()}}{ 122 | Clean up resources (close connections, etc.) 123 | \subsection{Usage}{ 124 | \if{html}{\out{
}}\preformatted{DataSource$cleanup()}\if{html}{\out{
}}
125 | }
126 |
127 | \subsection{Returns}{
128 | NULL (invisibly)
129 | }
130 | }
131 | \if{html}{\out{}} 132 | \if{html}{\out{}} 133 | \if{latex}{\out{\hypertarget{method-DataSource-clone}{}}} 134 | \subsection{Method \code{clone()}}{ 135 | The objects of this class are cloneable with this method. 136 | \subsection{Usage}{ 137 | \if{html}{\out{
}}\preformatted{DataSource$clone(deep = FALSE)}\if{html}{\out{
}}
138 | }
139 |
140 | \subsection{Arguments}{
141 | \if{html}{\out{}}
142 | \describe{
143 | \item{\code{deep}}{Whether to make a deep clone.}
144 | }
145 | \if{html}{\out{
}}
146 | }
147 | }
148 | }
149 |
--------------------------------------------------------------------------------
/docs/logo-python.svg:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
124 |
--------------------------------------------------------------------------------
/pkg-py/docs/data-sources.qmd:
--------------------------------------------------------------------------------
1 | ---
2 | title: Data Sources
3 | lightbox: true
4 | ---
5 |
6 | `querychat` supports many types of data sources, including:
7 |
8 | 1. Any [narwhals-compatible](https://narwhals-dev.github.io/narwhals/) data frame.
9 | 2. Any [SQLAlchemy](https://www.sqlalchemy.org/) database.
10 | 3. A custom [DataSource](reference/types.DataSource.qmd) interface/protocol.
11 |
12 | The sections below describe how to use each type of data source with `querychat`.
13 |
14 |
15 | ## Data frames
16 |
17 | You can use any [narwhals-compatible](https://narwhals-dev.github.io/narwhals/) data frame as a data source in `querychat`. This includes popular data frame libraries like [pandas](https://pandas.pydata.org/), [polars](https://www.pola.rs/), [pyarrow](https://arrow.apache.org/docs/python/), and many more.
18 |
19 | ::: {.panel-tabset .panel-pills}
20 |
21 | ### Pandas
22 |
23 | ```{.python filename="pandas-app.py"}
24 | import pandas as pd
25 | from querychat import QueryChat
26 |
27 | mtcars = pd.read_csv(
28 | "https://gist.githubusercontent.com/seankross/a412dfbd88b3db70b74b/raw/5f23f993cd87c283ce766e7ac6b329ee7cc2e1d1/mtcars.csv"
29 | )
30 |
31 | qc = QueryChat(mtcars, "mtcars")
32 | app = qc.app()
33 | ```
34 |
35 | ### Polars
36 |
37 | ```{.python filename="polars-app.py"}
38 | import polars as pl
39 | from querychat import QueryChat
40 |
41 | mtcars = pl.read_csv(
42 | "https://gist.githubusercontent.com/seankross/a412dfbd88b3db70b74b/raw/5f23f993cd87c283ce766e7ac6b329ee7cc2e1d1/mtcars.csv"
43 | )
44 |
45 | qc = QueryChat(mtcars, "mtcars")
46 | app = qc.app()
47 | ```
48 |
49 | ### Pyarrow
50 |
51 | ```{.python filename="pyarrow-app.py"}
52 | import pyarrow as pa
53 | import pyarrow.csv as pv
54 | from querychat import QueryChat
55 |
56 | mtcars = pv.read_csv(
57 | "https://gist.githubusercontent.com/seankross/a412dfbd88b3db70b74b/raw/5f23f993cd87c283ce766e7ac6b329ee7cc2e1d1/mtcars.csv"
58 | ).to_table()
59 |
60 | qc = QueryChat(mtcars, "mtcars")
61 | app = qc.app()
62 | ```
63 |
64 | :::
65 |
66 | If you're [building an app](build.qmd), note you can read the queried data frame reactively using the `df()` method, which returns a `pandas.DataFrame` by default.
67 |
68 | ## Databases
69 |
70 | You can also connect `querychat` directly to any database supported by [SQLAlchemy](https://www.sqlalchemy.org/). This includes popular databases like SQLite, DuckDB, PostgreSQL, MySQL, and many more.
71 |
72 | Assuming you have a database set up and accessible, you can pass a SQLAlchemy [database URL](https://docs.sqlalchemy.org/en/20/core/engines.html) to `create_engine()`, and then pass the resulting engine to `QueryChat`. Below are some examples for common databases.
73 |
74 |
75 | ::: {.panel-tabset}
76 |
77 | ### Duck DB
78 |
79 | ```shell
80 | pip install duckdb duckdb-engine
81 | ```
82 |
83 | ```{.python filename="duckdb-app.py"}
84 | from pathlib import Path
85 | from sqlalchemy import create_engine
86 | from querychat import QueryChat
87 |
88 | # Assumes my_database.duckdb is in the same directory as this script
89 | db_path = Path(__file__).parent / "my_database.duckdb"
90 | engine = create_engine(f"duckdb:///{db_path}")
91 |
92 | qc = QueryChat(engine, "my_table")
93 | app = qc.app()
94 | ```
95 |
96 | ### SQLite
97 |
98 | ```{.python filename="sqlite-app.py"}
99 | from pathlib import Path
100 | from sqlalchemy import create_engine
101 | from querychat import QueryChat
102 |
103 | # Assumes my_database.db is in the same directory as this script
104 | db_path = Path(__file__).parent / "my_database.db"
105 | engine = create_engine(f"sqlite:///{db_path}")
106 |
107 | qc = QueryChat(engine, "my_table")
108 | app = qc.app()
109 | ```
110 |
111 |
112 | ### PostgreSQL
113 |
114 | ```shell
115 | pip install psycopg2-binary
116 | ```
117 |
118 | ```{.python filename="postgresql-app.py"}
119 | from sqlalchemy import create_engine
120 | from querychat import QueryChat
121 |
122 | engine = create_engine("postgresql+psycopg2://user:password@localhost:5432/mydatabase")
123 | qc = QueryChat(engine, "my_table")
124 | app = qc.app()
125 | ```
126 |
127 | ### MySQL
128 |
129 | ```shell
130 | pip install pymysql
131 | ```
132 |
133 | ```{.python filename="mysql-app.py"}
134 | from sqlalchemy import create_engine
135 | from querychat import QueryChat
136 |
137 | engine = create_engine("mysql+pymysql://user:password@localhost:3306/mydatabase")
138 | qc = QueryChat(engine, "my_table")
139 | app = qc.app()
140 | ```
141 |
142 | :::
143 |
144 |
145 | If you don't have a database set up, you can easily create a local DuckDB database from a CSV file using the following code:
146 |
147 | ```{.python filename="create-duckdb.py"}
148 | import duckdb
149 |
150 | conn = duckdb.connect("my_database.duckdb")
151 |
152 | conn.execute("""
153 | CREATE TABLE my_table AS
154 | SELECT * FROM read_csv_auto('path/to/your/file.csv')
155 | """)
156 | ```
157 |
158 | Or, if you have a pandas DataFrame, you can create the DuckDB database like so:
159 |
160 | ```{.python filename="create-duckdb-from-pandas.py"}
161 | import duckdb
162 | import pandas as pd
163 | from querychat.data import titanic
164 |
165 | conn = duckdb.connect("my_database.duckdb")
166 | conn.register('titanic_df', titanic())
167 | conn.execute("""
168 | CREATE TABLE titanic AS
169 | SELECT * FROM titanic_df
170 | """)
171 | ```
172 |
173 | Then you can connect to this database using the DuckDB example above (changing the table name as appropriate):
174 |
175 | ## Custom sources
176 |
177 | If you have a custom data source that doesn't fit into the above categories, you can implement the [DataSource](reference/types.DataSource.qmd) interface/protocol. This requires implementing methods for getting schema information and executing queries.
--------------------------------------------------------------------------------
/pkg-r/tests/testthat/_snaps/DataSource.md:
--------------------------------------------------------------------------------
1 | # DataSource base class / throws not_implemented_error for all abstract methods
2 |
3 | Code
4 | base_source$get_db_type()
5 | Condition
6 | Error in `base_source$get_db_type()`:
7 | ! `get_db_type()` must be implemented by subclass
8 |
9 | ---
10 |
11 | Code
12 | base_source$get_schema()
13 | Condition
14 | Error in `base_source$get_schema()`:
15 | ! `get_schema()` must be implemented by subclass
16 |
17 | ---
18 |
19 | Code
20 | base_source$execute_query("SELECT * FROM test")
21 | Condition
22 | Error in `base_source$execute_query()`:
23 | ! `execute_query()` must be implemented by subclass
24 |
25 | ---
26 |
27 | Code
28 | base_source$test_query("SELECT * FROM test LIMIT 1")
29 | Condition
30 | Error in `base_source$test_query()`:
31 | ! `test_query()` must be implemented by subclass
32 |
33 | ---
34 |
35 | Code
36 | base_source$get_data()
37 | Condition
38 | Error in `base_source$get_data()`:
39 | ! `get_data()` must be implemented by subclass
40 |
41 | ---
42 |
43 | Code
44 | base_source$cleanup()
45 | Condition
46 | Error in `base_source$cleanup()`:
47 | ! `cleanup()` must be implemented by subclass
48 |
49 | # DataFrameSource$new() / errors with non-data.frame input
50 |
51 | Code
52 | DataFrameSource$new(list(a = 1, b = 2), "test_table")
53 | Condition
54 | Error in `initialize()`:
55 | ! `df` must be a data frame, not a list.
56 |
57 | ---
58 |
59 | Code
60 | DataFrameSource$new(c(1, 2, 3), "test_table")
61 | Condition
62 | Error in `initialize()`:
63 | ! `df` must be a data frame, not a double vector.
64 |
65 | ---
66 |
67 | Code
68 | DataFrameSource$new(NULL, "test_table")
69 | Condition
70 | Error in `initialize()`:
71 | ! `df` must be a data frame, not `NULL`.
72 |
73 | # DataFrameSource$new() / errors with invalid table names
74 |
75 | Code
76 | DataFrameSource$new(test_df, "123_invalid")
77 | Condition
78 | Error in `initialize()`:
79 | ! `table_name` must be a valid SQL table name
80 | i Table names must begin with a letter and contain only letters, numbers, and underscores
81 | x You provided: "123_invalid"
82 | Code
83 | DataFrameSource$new(test_df, "table-name")
84 | Condition
85 | Error in `initialize()`:
86 | ! `table_name` must be a valid SQL table name
87 | i Table names must begin with a letter and contain only letters, numbers, and underscores
88 | x You provided: "table-name"
89 | Code
90 | DataFrameSource$new(test_df, "table name")
91 | Condition
92 | Error in `initialize()`:
93 | ! `table_name` must be a valid SQL table name
94 | i Table names must begin with a letter and contain only letters, numbers, and underscores
95 | x You provided: "table name"
96 | Code
97 | DataFrameSource$new(test_df, "")
98 | Condition
99 | Error in `initialize()`:
100 | ! `table_name` must be a valid SQL table name
101 | i Table names must begin with a letter and contain only letters, numbers, and underscores
102 | x You provided: ""
103 | Code
104 | DataFrameSource$new(test_df, NULL)
105 | Condition
106 | Error in `initialize()`:
107 | ! `table_name` must be a single string, not `NULL`.
108 |
109 | # DBISource$new() / errors with non-DBI connection
110 |
111 | Code
112 | DBISource$new(list(fake = "connection"), "test_table")
113 | Condition
114 | Error in `initialize()`:
115 | ! `conn` must be a }} 54 | \if{html}{\out{}} 55 | \if{latex}{\out{\hypertarget{method-DataFrameSource-new}{}}} 56 | \subsection{Method \code{new()}}{ 57 | Create a new DataFrameSource 58 | \subsection{Usage}{ 59 | \if{html}{\out{
}}\preformatted{DataFrameSource$new(df, table_name)}\if{html}{\out{
}}
60 | }
61 |
62 | \subsection{Arguments}{
63 | \if{html}{\out{}}
64 | \describe{
65 | \item{\code{df}}{A data frame.}
66 |
67 | \item{\code{table_name}}{Name to use for the table in SQL queries. Must be a
68 | valid table name (start with letter, contain only letters, numbers,
69 | and underscores)}
70 | }
71 | \if{html}{\out{
}}
72 | }
73 | \subsection{Returns}{
74 | A new DataFrameSource object
75 | }
76 | \subsection{Examples}{
77 | \if{html}{\out{}}
78 | \preformatted{\dontrun{
79 | source <- DataFrameSource$new(iris, "iris")
80 | }
81 | }
82 | \if{html}{\out{
}}
83 |
84 | }
85 |
86 | }
87 | \if{html}{\out{}} 88 | \if{html}{\out{}} 89 | \if{latex}{\out{\hypertarget{method-DataFrameSource-get_db_type}{}}} 90 | \subsection{Method \code{get_db_type()}}{ 91 | Get the database type 92 | \subsection{Usage}{ 93 | \if{html}{\out{
}}\preformatted{DataFrameSource$get_db_type()}\if{html}{\out{
}}
94 | }
95 |
96 | \subsection{Returns}{
97 | The string "DuckDB"
98 | }
99 | }
100 | \if{html}{\out{}} 101 | \if{html}{\out{}} 102 | \if{latex}{\out{\hypertarget{method-DataFrameSource-get_schema}{}}} 103 | \subsection{Method \code{get_schema()}}{ 104 | Get schema information for the data frame 105 | \subsection{Usage}{ 106 | \if{html}{\out{
}}\preformatted{DataFrameSource$get_schema(categorical_threshold = 20)}\if{html}{\out{
}}
107 | }
108 |
109 | \subsection{Arguments}{
110 | \if{html}{\out{}}
111 | \describe{
112 | \item{\code{categorical_threshold}}{Maximum number of unique values for a text
113 | column to be considered categorical (default: 20)}
114 | }
115 | \if{html}{\out{
}}
116 | }
117 | \subsection{Returns}{
118 | A string describing the schema
119 | }
120 | }
121 | \if{html}{\out{}} 122 | \if{html}{\out{}} 123 | \if{latex}{\out{\hypertarget{method-DataFrameSource-execute_query}{}}} 124 | \subsection{Method \code{execute_query()}}{ 125 | Execute a SQL query 126 | \subsection{Usage}{ 127 | \if{html}{\out{
}}\preformatted{DataFrameSource$execute_query(query)}\if{html}{\out{
}}
128 | }
129 |
130 | \subsection{Arguments}{
131 | \if{html}{\out{}}
132 | \describe{
133 | \item{\code{query}}{SQL query string. If NULL or empty, returns all data}
134 | }
135 | \if{html}{\out{
}}
136 | }
137 | \subsection{Returns}{
138 | A data frame with query results
139 | }
140 | }
141 | \if{html}{\out{}} 142 | \if{html}{\out{}} 143 | \if{latex}{\out{\hypertarget{method-DataFrameSource-test_query}{}}} 144 | \subsection{Method \code{test_query()}}{ 145 | Test a SQL query by fetching only one row 146 | \subsection{Usage}{ 147 | \if{html}{\out{
}}\preformatted{DataFrameSource$test_query(query)}\if{html}{\out{
}}
148 | }
149 |
150 | \subsection{Arguments}{
151 | \if{html}{\out{}}
152 | \describe{
153 | \item{\code{query}}{SQL query string}
154 | }
155 | \if{html}{\out{
}}
156 | }
157 | \subsection{Returns}{
158 | A data frame with one row of results
159 | }
160 | }
161 | \if{html}{\out{}} 162 | \if{html}{\out{}} 163 | \if{latex}{\out{\hypertarget{method-DataFrameSource-get_data}{}}} 164 | \subsection{Method \code{get_data()}}{ 165 | Get all data from the table 166 | \subsection{Usage}{ 167 | \if{html}{\out{
}}\preformatted{DataFrameSource$get_data()}\if{html}{\out{
}}
168 | }
169 |
170 | \subsection{Returns}{
171 | A data frame containing all data
172 | }
173 | }
174 | \if{html}{\out{}} 175 | \if{html}{\out{}} 176 | \if{latex}{\out{\hypertarget{method-DataFrameSource-cleanup}{}}} 177 | \subsection{Method \code{cleanup()}}{ 178 | Close the DuckDB connection 179 | \subsection{Usage}{ 180 | \if{html}{\out{
}}\preformatted{DataFrameSource$cleanup()}\if{html}{\out{
}}
181 | }
182 |
183 | \subsection{Returns}{
184 | NULL (invisibly)
185 | }
186 | }
187 | \if{html}{\out{}} 188 | \if{html}{\out{}} 189 | \if{latex}{\out{\hypertarget{method-DataFrameSource-clone}{}}} 190 | \subsection{Method \code{clone()}}{ 191 | The objects of this class are cloneable with this method. 192 | \subsection{Usage}{ 193 | \if{html}{\out{
}}\preformatted{DataFrameSource$clone(deep = FALSE)}\if{html}{\out{
}}
194 | }
195 |
196 | \subsection{Arguments}{
197 | \if{html}{\out{}}
198 | \describe{
199 | \item{\code{deep}}{Whether to make a deep clone.}
200 | }
201 | \if{html}{\out{
}}
202 | }
203 | }
204 | }
205 |
--------------------------------------------------------------------------------
/pkg-py/src/querychat/_querychat_module.py:
--------------------------------------------------------------------------------
1 | from __future__ import annotations
2 |
3 | import copy
4 | import warnings
5 | from dataclasses import dataclass
6 | from pathlib import Path
7 | from typing import TYPE_CHECKING, Union
8 |
9 | import shinychat
10 | from shiny import module, reactive, ui
11 |
12 | from .tools import tool_query, tool_reset_dashboard, tool_update_dashboard
13 |
14 | if TYPE_CHECKING:
15 | from collections.abc import Callable
16 |
17 | import chatlas
18 | import pandas as pd
19 | from shiny import Inputs, Outputs, Session
20 | from shiny.bookmark import BookmarkState, RestoreState
21 |
22 | from ._datasource import DataSource
23 |
24 | ReactiveString = reactive.Value[str]
25 | """A reactive string value."""
26 | ReactiveStringOrNone = reactive.Value[Union[str, None]]
27 | """A reactive string (or None) value."""
28 |
29 | CHAT_ID = "chat"
30 |
31 |
32 | @module.ui
33 | def mod_ui(**kwargs):
34 | css_path = Path(__file__).parent / "static" / "css" / "styles.css"
35 | js_path = Path(__file__).parent / "static" / "js" / "querychat.js"
36 |
37 | tag = shinychat.chat_ui(CHAT_ID, **kwargs)
38 | tag.add_class("querychat")
39 |
40 | return ui.TagList(
41 | ui.head_content(
42 | ui.include_css(css_path),
43 | ui.include_js(js_path),
44 | ),
45 | tag,
46 | )
47 |
48 |
49 | @dataclass
50 | class ServerValues:
51 | """
52 | Session-specific reactive values and client returned by QueryChat.server().
53 |
54 | This dataclass contains all the session-specific reactive state for a QueryChat
55 | instance. Each session gets its own ServerValues to ensure proper isolation
56 | between concurrent sessions.
57 |
58 | Attributes
59 | ----------
60 | df
61 | A reactive Calc that returns the current filtered data frame. If no SQL
62 | query has been set, this returns the unfiltered data from the data source.
63 | Call it like `.df()` to reactively read the current data frame.
64 | sql
65 | A reactive Value containing the current SQL query string. Access the value
66 | by calling `.sql()`, or set it with `.sql.set("SELECT ...")`.
67 | Returns `None` if no query has been set.
68 | title
69 | A reactive Value containing the current title for the query. The LLM
70 | provides this title when generating a new SQL query. Access it with
71 | `.title()`, or set it with `.title.set("...")`. Returns
72 | `None` if no title has been set.
73 | client
74 | The session-specific chat client instance. This is a deep copy of the
75 | base client configured for this specific session, containing the chat
76 | history and tool registrations for this session only.
77 |
78 | """
79 |
80 | df: Callable[[], pd.DataFrame]
81 | sql: ReactiveStringOrNone
82 | title: ReactiveStringOrNone
83 | client: chatlas.Chat
84 |
85 |
86 | @module.server
87 | def mod_server(
88 | input: Inputs,
89 | output: Outputs,
90 | session: Session,
91 | *,
92 | data_source: DataSource,
93 | greeting: str | None,
94 | client: chatlas.Chat,
95 | enable_bookmarking: bool,
96 | ):
97 | # Reactive values to store state
98 | sql = ReactiveStringOrNone(None)
99 | title = ReactiveStringOrNone(None)
100 | has_greeted = reactive.value[bool](False) # noqa: FBT003
101 |
102 | # Set up the chat object for this session
103 | chat = copy.deepcopy(client)
104 |
105 | # Create the tool functions
106 | update_dashboard_tool = tool_update_dashboard(data_source, sql, title)
107 | reset_dashboard_tool = tool_reset_dashboard(sql, title)
108 | query_tool = tool_query(data_source)
109 |
110 | # Register tools with annotations for the UI
111 | chat.register_tool(update_dashboard_tool)
112 | chat.register_tool(query_tool)
113 | chat.register_tool(reset_dashboard_tool)
114 |
115 | # Execute query when SQL changes
116 | @reactive.calc
117 | def filtered_df():
118 | query = sql.get()
119 | if not query:
120 | return data_source.get_data()
121 | else:
122 | return data_source.execute_query(query)
123 |
124 | # Chat UI logic
125 | chat_ui = shinychat.Chat(CHAT_ID)
126 |
127 | # Handle user input
128 | @chat_ui.on_user_submit
129 | async def _(user_input: str):
130 | stream = await chat.stream_async(user_input, echo="none", content="all")
131 | await chat_ui.append_message_stream(stream)
132 |
133 | @reactive.effect
134 | async def greet_on_startup():
135 | if has_greeted():
136 | return
137 |
138 | if greeting:
139 | await chat_ui.append_message(greeting)
140 | elif greeting is None:
141 | warnings.warn(
142 | "No greeting provided to `QueryChat()`. Using the LLM `client` to generate one now. "
143 | "For faster startup, lower cost, and determinism, consider providing a greeting "
144 | "to `QueryChat()` and `.generate_greeting()` to generate one beforehand.",
145 | GreetWarning,
146 | stacklevel=2,
147 | )
148 | stream = await chat.stream_async(GREETING_PROMPT, echo="none")
149 | await chat_ui.append_message_stream(stream)
150 |
151 | has_greeted.set(True)
152 |
153 | # Handle update button clicks
154 | @reactive.effect
155 | @reactive.event(input.chat_update)
156 | def _():
157 | update = input.chat_update()
158 | if update is None:
159 | return
160 | if not isinstance(update, dict):
161 | return
162 |
163 | new_query = update.get("query")
164 | new_title = update.get("title")
165 | if new_query is not None:
166 | sql.set(new_query)
167 | if new_title is not None:
168 | title.set(new_title)
169 |
170 | if enable_bookmarking:
171 | chat_ui.enable_bookmarking(client)
172 |
173 | @session.bookmark.on_bookmark
174 | def _on_bookmark(x: BookmarkState) -> None:
175 | vals = x.values # noqa: PD011
176 | vals["querychat_sql"] = sql.get()
177 | vals["querychat_title"] = title.get()
178 | vals["querychat_has_greeted"] = has_greeted.get()
179 |
180 | @session.bookmark.on_restore
181 | def _on_restore(x: RestoreState) -> None:
182 | vals = x.values # noqa: PD011
183 | if "querychat_sql" in vals:
184 | sql.set(vals["querychat_sql"])
185 | if "querychat_title" in vals:
186 | title.set(vals["querychat_title"])
187 | if "querychat_has_greeted" in vals:
188 | has_greeted.set(vals["querychat_has_greeted"])
189 |
190 | return ServerValues(df=filtered_df, sql=sql, title=title, client=chat)
191 |
192 |
193 | GREETING_PROMPT: str = "Please give me a friendly greeting. Include a few sample prompts in a two-level bulleted list."
194 |
195 |
196 | class GreetWarning(Warning):
197 | """Warning raised when no greeting is provided to QueryChat."""
198 |
--------------------------------------------------------------------------------
/pkg-r/man/DBISource.Rd:
--------------------------------------------------------------------------------
1 | % Generated by roxygen2: do not edit by hand
2 | % Please edit documentation in R/DataSource.R
3 | \name{DBISource}
4 | \alias{DBISource}
5 | \title{DBI Source}
6 | \description{
7 | A DataSource implementation for DBI database connections (SQLite, PostgreSQL,
8 | MySQL, etc.).
9 | }
10 | \details{
11 | This class wraps a DBI connection and provides SQL query execution against
12 | a specified table in the database.
13 | }
14 | \examples{
15 | \dontrun{
16 | # Connect to a database
17 | conn <- DBI::dbConnect(RSQLite::SQLite(), ":memory:")
18 | DBI::dbWriteTable(conn, "mtcars", mtcars)
19 |
20 | # Create a DBI source
21 | db_source <- DBISource$new(conn, "mtcars")
22 |
23 | # Get database type
24 | db_source$get_db_type() # Returns "SQLite"
25 |
26 | # Execute a query
27 | result <- db_source$execute_query("SELECT * FROM mtcars WHERE mpg > 25")
28 |
29 | # Note: cleanup() will disconnect the connection
30 | # If you want to keep the connection open, don't call cleanup()
31 | }
32 |
33 | ## ------------------------------------------------
34 | ## Method `DBISource$new`
35 | ## ------------------------------------------------
36 |
37 | \dontrun{
38 | conn <- DBI::dbConnect(RSQLite::SQLite(), ":memory:")
39 | DBI::dbWriteTable(conn, "iris", iris)
40 | source <- DBISource$new(conn, "iris")
41 | }
42 | }
43 | \section{Super class}{
44 | \code{\link[querychat:DataSource]{querychat::DataSource}} -> \code{DBISource}
45 | }
46 | \section{Methods}{
47 | \subsection{Public methods}{
48 | \itemize{
49 | \item \href{#method-DBISource-new}{\code{DBISource$new()}}
50 | \item \href{#method-DBISource-get_db_type}{\code{DBISource$get_db_type()}}
51 | \item \href{#method-DBISource-get_schema}{\code{DBISource$get_schema()}}
52 | \item \href{#method-DBISource-execute_query}{\code{DBISource$execute_query()}}
53 | \item \href{#method-DBISource-test_query}{\code{DBISource$test_query()}}
54 | \item \href{#method-DBISource-get_data}{\code{DBISource$get_data()}}
55 | \item \href{#method-DBISource-cleanup}{\code{DBISource$cleanup()}}
56 | \item \href{#method-DBISource-clone}{\code{DBISource$clone()}}
57 | }
58 | }
59 | \if{html}{\out{}} 60 | \if{html}{\out{}} 61 | \if{latex}{\out{\hypertarget{method-DBISource-new}{}}} 62 | \subsection{Method \code{new()}}{ 63 | Create a new DBISource 64 | \subsection{Usage}{ 65 | \if{html}{\out{
}}\preformatted{DBISource$new(conn, table_name)}\if{html}{\out{
}}
66 | }
67 |
68 | \subsection{Arguments}{
69 | \if{html}{\out{}}
70 | \describe{
71 | \item{\code{conn}}{A DBI connection object}
72 |
73 | \item{\code{table_name}}{Name of the table in the database. Can be a character
74 | string or a \code{\link[DBI:Id]{DBI::Id()}} object for tables in catalogs/schemas}
75 | }
76 | \if{html}{\out{
}}
77 | }
78 | \subsection{Returns}{
79 | A new DBISource object
80 | }
81 | \subsection{Examples}{
82 | \if{html}{\out{}}
83 | \preformatted{\dontrun{
84 | conn <- DBI::dbConnect(RSQLite::SQLite(), ":memory:")
85 | DBI::dbWriteTable(conn, "iris", iris)
86 | source <- DBISource$new(conn, "iris")
87 | }
88 | }
89 | \if{html}{\out{
}}
90 |
91 | }
92 |
93 | }
94 | \if{html}{\out{}} 95 | \if{html}{\out{}} 96 | \if{latex}{\out{\hypertarget{method-DBISource-get_db_type}{}}} 97 | \subsection{Method \code{get_db_type()}}{ 98 | Get the database type 99 | \subsection{Usage}{ 100 | \if{html}{\out{
}}\preformatted{DBISource$get_db_type()}\if{html}{\out{
}}
101 | }
102 |
103 | \subsection{Returns}{
104 | A string identifying the database type
105 | }
106 | }
107 | \if{html}{\out{}} 108 | \if{html}{\out{}} 109 | \if{latex}{\out{\hypertarget{method-DBISource-get_schema}{}}} 110 | \subsection{Method \code{get_schema()}}{ 111 | Get schema information for the database table 112 | \subsection{Usage}{ 113 | \if{html}{\out{
}}\preformatted{DBISource$get_schema(categorical_threshold = 20)}\if{html}{\out{
}}
114 | }
115 |
116 | \subsection{Arguments}{
117 | \if{html}{\out{}}
118 | \describe{
119 | \item{\code{categorical_threshold}}{Maximum number of unique values for a text
120 | column to be considered categorical (default: 20)}
121 | }
122 | \if{html}{\out{
}}
123 | }
124 | \subsection{Returns}{
125 | A string describing the schema
126 | }
127 | }
128 | \if{html}{\out{}} 129 | \if{html}{\out{}} 130 | \if{latex}{\out{\hypertarget{method-DBISource-execute_query}{}}} 131 | \subsection{Method \code{execute_query()}}{ 132 | Execute a SQL query 133 | \subsection{Usage}{ 134 | \if{html}{\out{
}}\preformatted{DBISource$execute_query(query)}\if{html}{\out{
}}
135 | }
136 |
137 | \subsection{Arguments}{
138 | \if{html}{\out{}}
139 | \describe{
140 | \item{\code{query}}{SQL query string. If NULL or empty, returns all data}
141 | }
142 | \if{html}{\out{
}}
143 | }
144 | \subsection{Returns}{
145 | A data frame with query results
146 | }
147 | }
148 | \if{html}{\out{}} 149 | \if{html}{\out{}} 150 | \if{latex}{\out{\hypertarget{method-DBISource-test_query}{}}} 151 | \subsection{Method \code{test_query()}}{ 152 | Test a SQL query by fetching only one row 153 | \subsection{Usage}{ 154 | \if{html}{\out{
}}\preformatted{DBISource$test_query(query)}\if{html}{\out{
}}
155 | }
156 |
157 | \subsection{Arguments}{
158 | \if{html}{\out{}}
159 | \describe{
160 | \item{\code{query}}{SQL query string}
161 | }
162 | \if{html}{\out{
}}
163 | }
164 | \subsection{Returns}{
165 | A data frame with one row of results
166 | }
167 | }
168 | \if{html}{\out{}} 169 | \if{html}{\out{}} 170 | \if{latex}{\out{\hypertarget{method-DBISource-get_data}{}}} 171 | \subsection{Method \code{get_data()}}{ 172 | Get all data from the table 173 | \subsection{Usage}{ 174 | \if{html}{\out{
}}\preformatted{DBISource$get_data()}\if{html}{\out{
}}
175 | }
176 |
177 | \subsection{Returns}{
178 | A data frame containing all data
179 | }
180 | }
181 | \if{html}{\out{}} 182 | \if{html}{\out{}} 183 | \if{latex}{\out{\hypertarget{method-DBISource-cleanup}{}}} 184 | \subsection{Method \code{cleanup()}}{ 185 | Disconnect from the database 186 | \subsection{Usage}{ 187 | \if{html}{\out{
}}\preformatted{DBISource$cleanup()}\if{html}{\out{
}}
188 | }
189 |
190 | \subsection{Returns}{
191 | NULL (invisibly)
192 | }
193 | }
194 | \if{html}{\out{}} 195 | \if{html}{\out{}} 196 | \if{latex}{\out{\hypertarget{method-DBISource-clone}{}}} 197 | \subsection{Method \code{clone()}}{ 198 | The objects of this class are cloneable with this method. 199 | \subsection{Usage}{ 200 | \if{html}{\out{
}}\preformatted{DBISource$clone(deep = FALSE)}\if{html}{\out{
}}
201 | }
202 |
203 | \subsection{Arguments}{
204 | \if{html}{\out{}}
205 | \describe{
206 | \item{\code{deep}}{Whether to make a deep clone.}
207 | }
208 | \if{html}{\out{
}}
209 | }
210 | }
211 | }
212 |
--------------------------------------------------------------------------------