querychat

A self-service analytics platform

Give users a natural language interface to your data — in 3 lines.

querychat is the capstone of the day. It combines everything we’ve learned: chatlas for the LLM client, shinychat for the UI, and adds purpose-built tools for data exploration. The result is a self-service analytics platform that’s safe to hand to non-technical users.

The 3-line analytics app

app.py

from querychat import QueryChat
from querychat.data import titanic

qc = QueryChat(titanic(), "titanic")
app = qc.app()

shiny run app.py

Live demo: create this file, run it, open the browser. You get a full chat interface that can filter, query, and (optionally) visualize the Titanic dataset — from 3 lines.

Let them play with it for 30 seconds. Ask “show me all first-class passengers who survived” or “what was the average fare by class?” to demonstrate both the filter and query tools.

A real dashboard

app.py

from shiny.express import render, ui
from querychat.express import QueryChat
from querychat.data import titanic

qc = QueryChat(titanic(), "titanic")
qc.sidebar()

with ui.card():
    with ui.card_header():
        @render.text
        def title():
            return qc.title() or "Titanic Dataset"

    @render.data_frame
    def data_table():
        return qc.df()

ui.page_opts(fillable=True, title="Titanic Explorer")

This is the pattern people will actually use. qc.sidebar() places the chat in a sidebar. qc.df() is a reactive value — the data table re-renders automatically when the user filters through the chat.

Point out: qc.df() and qc.title() are the integration points. Any Shiny output that reads qc.df() — a table, a plot, a summary stat — will update automatically. This is the power of Shiny’s reactivity.

Built-in tools

Tool	What it does	User sees
filter	SELECT * WHERE ... — updates the dashboard	Data table + title update
query	Arbitrary analytics SQL — returns results	SQL + result table in chat
visualize	SQL + chart spec — renders inline	Altair chart in chat

# Default: filter + query
qc = QueryChat(df, "data")

# All three
qc = QueryChat(df, "data", tools=("filter", "query", "visualize"))

All tools are read-only — no INSERT, UPDATE, or DELETE.

Walk through the three tools:

1. filter is the most common — the user says “show me rows where X”, and the dashboard filters. The LLM writes a SQL WHERE clause, querychat validates and executes it, and qc.df() updates reactively.

2. query is for analytics — “what’s the average tip by day?” The LLM writes full SQL, the result appears as a table in the chat.

3. visualize is opt-in (requires pip install "querychat[viz]"). It uses a SQL extension that generates Altair charts.

All three are read-only by design. The SQL is validated before execution.

Tools in action

SCREENSHOT: querychat Titanic app showing a conversation —
1. User asks “show me first-class passengers who survived” → dashboard filters
2. User asks “what was the survival rate by class?” → query result table in chat
(capture a real session to show the natural flow)

If time permits, do this live instead of a screenshot. The key thing the audience should see: the user types natural language, the LLM writes SQL, and the result appears either in the dashboard (filter) or inline (query). The user never sees or writes SQL — but they could inspect it if they wanted.

Context management

querychat auto-generates context from your data:

Auto-generated

• Column names and SQL types
• Numeric ranges (min/max)
• Categorical values (≤20 unique)

The LLM knows your schema without seeing your data.

User-supplied

QueryChat(
    df, "titanic",
    data_description=(
        "survived: 1 = survived, "
        "0 = did not survive"
    ),
    extra_instructions=(
        "Use British spelling. "
        "Refuse off-topic questions."
    ),
)

This is the “context engineering” theme paying off. Auto-generated context means the LLM understands the shape of the data (what columns exist, what values are valid) without ever seeing the raw rows. This is both a correctness benefit (the LLM writes valid SQL) and a privacy benefit (no data leaks to the provider).

User-supplied context adds domain knowledge the schema alone can’t convey: what does survived=1 mean? What tone should the assistant use? This goes in data_description (about the data) or extra_instructions (about behavior).

Both can be inline strings or paths to markdown files.

The security model

❌ The naive approach

Send your CSV to the LLM.

• Data leaves your server
• Doesn’t scale past ~100K rows
• No reproducibility
• No verification

✅ The querychat approach

LLM writes SQL. You execute it locally.

• Data stays on your server
• Scales via DuckDB
• SQL is reproducible
• SQL is verifiable and read-only

The LLM is a translator (language → SQL), not a database.

This is the philosophical payoff of the whole day. Remember slide 1 of the foundations section: “focus LLMs on what they’re good at (language → code), engineer around the bad.” querychat does exactly this.

The LLM never sees the actual data rows (except query tool results). It sees the schema context, writes SQL, and querychat executes it in a local DuckDB instance. The SQL is validated (read-only, no DDL) before execution.

This means: - You can use querychat with sensitive data (it doesn’t leave your server) - You can use it with large datasets (DuckDB handles it, not the LLM context) - Every result is reproducible (you have the SQL) - Every result is verifiable (the user can read the SQL)

This is “show your work” from the correctness slide, implemented as architecture.

Works everywhere

Shiny ✨

Best experience — native reactivity. qc.df() drives the whole dashboard.

Streamlit

from querychat.streamlit \
    import QueryChat

Dash

from querychat.dash \
    import QueryChat

Gradio

from querychat.gradio \
    import QueryChat

Same QueryChat API — swap the import, keep your code.

Brief slide. querychat supports four frameworks with the same core API. Shiny gives the best experience because qc.df() is a true reactive value — in Streamlit/Dash/Gradio, the integration is more manual. But the same QueryChat constructor and tools work everywhere.

Don’t dwell — 30 seconds max. The point is: you’re not locked in.

Data sources

querychat works with data you already have:

import pandas as pd
from sqlalchemy import create_engine

# In-memory DataFrames (pandas, polars, pyarrow)
qc = QueryChat(pd.read_csv("sales.csv"), "sales")

# Databases (via SQLAlchemy)
engine = create_engine("duckdb:///warehouse.duckdb")
qc = QueryChat(engine, "transactions")

# Pins boards (shared data)
qc = QueryChat(board, "monthly_metrics")

Show the breadth of data sources. For the tutorial exercises, they’ll use in-memory DataFrames (simplest). But in production, the database path is powerful — you point querychat at your data warehouse and the LLM writes SQL against real tables.

Under the hood, DataFrame inputs are loaded into an in-memory DuckDB for SQL execution. This means even pandas DataFrames get DuckDB’s query performance.

🛠️ Hands-on: build your own analytics app

~15 minutes — work through as many as you can:

1️⃣ Your own data

Swap the Titanic dataset for your own CSV (or one we provide).

Add a data_description to help the LLM.

2️⃣ Add web search

Register tool_web_search() so the assistant can answer questions beyond the dataset.

3️⃣ Add a custom tool

Write a tool that does something the built-in tools can’t — e.g., export to CSV, send a summary email, etc.

Exercise file: exercises/03-querychat-starter.py

The exercise file starts with a working querychat app on the Titanic dataset. Task 1 is a data swap — if they don’t have their own CSV, have a few interesting ones ready (e.g., seaborn tips, Palmer penguins, a Kaggle dataset).

Task 2 adds web search — this extends the assistant beyond the dataset. The pattern is: get qc.client() and call register_tool(tool_web_search()).

Task 3 is open-ended. Ideas: a tool that saves the current filter as a bookmark, a tool that generates a matplotlib chart, a tool that exports the filtered data to CSV.

Float around and help. Common stumbles: - table_name must be alphanumeric (no hyphens or spaces) - visualize tool requires pip install "querychat[viz]" - Adding tools to a Shiny querychat app requires getting the client via qc.client() before the app starts