feat(pkg-py): Add support for streamlit, gradio, and dash

[cpsievert]

This PR extends querychat's Python package to support three additional web frameworks alongside Shiny: Streamlit, Gradio, and Dash. Each framework gets a dedicated QueryChat class with a consistent API for integrating natural language data exploration.

Key highlights:

• New framework-specific modules: querychat.streamlit, querychat.gradio, querychat.dash
• Unified architecture with shared QueryChatBase class and AppState for state management
• All frameworks provide .app() for quick start, .ui() for custom layouts
• Clickable suggestions work across all frameworks
• Comprehensive documentation with screenshots for each code example
• Playwright E2E tests covering all frameworks with new CI workflow

Breaking Changes

• df() return type: Methods like execute_query(), get_data(), and df() now return a narwhals.DataFrame instead of pandas.DataFrame. Call .to_native() to get a pandas DataFrame if needed.
• Install pandas/polars extras for SQLAlchemy support: pip install querychat[pandas] or pip install querychat[polars]

Architecture

The implementation follows a layered architecture:

┌─────────────────────────────────────────────────────────────┐
│                  Framework-specific classes                 │
│  StreamlitQueryChat │ GradioQueryChat │ DashQueryChat       │
│                     │                 │   + DashUI          │
├─────────────────────┴─────────────────┴─────────────────────┤
│                      QueryChatBase                          │
│  • Data source normalization                                │
│  • System prompt assembly                                   │
│  • Chat client configuration                                │
│  • client(), console(), generate_greeting()                 │
├─────────────────────────────────────────────────────────────┤
│                        AppState                             │
│  • Framework-agnostic session state                         │
│  • Serializable to dict for framework state stores          │
│  • Chat turn management via chatlas                         │
│  • stream_response() / stream_response_async()              │
└─────────────────────────────────────────────────────────────┘

Key design decisions:

• QueryChatBase centralizes common logic, framework classes inherit and add UI methods
• AppState can be serialized/deserialized for frameworks with external state stores (Gradio, Dash)
• Streamlit uses st.session_state directly; Gradio/Dash use gr.State/dcc.Store with serialized dicts
• Async streaming for Dash (via stream_response_async) to avoid blocking other callbacks

Framework Comparison

Feature	Shiny	Streamlit	Gradio	Dash
Quick start	.app()	.app()	.app()	.app()
Custom layout	.ui()/.sidebar()/.server()	.ui()/.sidebar()	.ui()	.ui() + .init_app()
State access	Reactive via .df()/.sql()/.title()	.df()/.sql()/.title()	.df(state)/.sql(state)/.title(state)	.df(state)/.sql(state)/.title(state)
Reset	Via chat	.reset() method	Button in .app()	Button in .app()
State storage	Shiny reactive	st.session_state	gr.State (dict)	dcc.Store (dict)

Usage Examples

# Streamlit
from querychat.streamlit import QueryChat
qc = QueryChat(df, "titanic")
qc.app()

# Gradio
from querychat.gradio import QueryChat
qc = QueryChat(df, "titanic")
qc.app().launch()

# Dash
from querychat.dash import QueryChat
qc = QueryChat(df, "titanic")
qc.app().run()

Installation

Each framework available as an optional extra:

pip install "querychat[streamlit]"
pip install "querychat[gradio]"
pip install "querychat[dash]"

Files Changed

Core infrastructure (~570 LOC):

• _querychat_base.py - Shared QueryChatBase class
• _querychat_core.py - AppState, streaming utilities, type definitions
• _ui_assets.py - CSS/JS assets for clickable suggestions
• Renamed _querychat.py → _shiny.py, _querychat_module.py → _shiny_module.py

Framework integrations (~1130 LOC):

• _streamlit.py (234 lines) - Session state integration, sidebar/ui methods
• _gradio.py (396 lines) - gr.State integration, GradioBlocksWrapper for 6.0+ compatibility
• _dash.py (504 lines) - dcc.Store integration, async callbacks, dash-ag-grid for data display
• _dash_ui.py (226 lines) - Dash UI component builders

Testing (~1500+ LOC):

• Playwright e2e tests: test_04_streamlit_apps.py, test_05_gradio_apps.py, test_06_dash_apps.py
• Unit tests: test_base.py, test_state.py, test_frameworks.py
• New GitHub Actions workflow: .github/workflows/py-e2e-test.yml

Documentation:

• build-intro.qmd - Framework-agnostic introduction
• build-streamlit.qmd, build-gradio.qmd, build-dash.qmd - Framework guides
• 15 new screenshots demonstrating example apps

For Reviewers

Key files to focus on:

1. _querychat_base.py - Core shared logic
2. _querychat_core.py - State management architecture
3. Framework implementations - Each follows similar patterns

Testing locally:

# Run all Python checks
make py-check

# Run Playwright e2e tests (requires setup first)
make py-e2e-setup
make py-e2e-tests

# Preview docs
make py-docs-preview

# Try individual examples
uv run streamlit run pkg-py/examples/04-streamlit-app.py
uv run python pkg-py/examples/05-gradio-app.py
uv run python pkg-py/examples/06-dash-app.py

Test Plan

• Unit tests pass (make py-check-tests)
• Type checks pass (make py-check-types)
• Linting passes (make py-check-format)
• Playwright e2e tests pass (make py-e2e-tests)
• Manual testing of example apps
• Documentation renders correctly (make py-docs-preview)

---

Generated with Claude Code

[gadenbuie]

Broad strokes: this looks great! I didn't review all the code in detail, but the architectural design choices seem sounds and you've nicely re-organized the querychat internals to be re-usable across so many backends. Nice work!