querychat 0.3.0__tar.gz → 0.4.0__tar.gz

{querychat-0.3.0 → querychat-0.4.0}/LICENSE.md

@@ -1,6 +1,6 @@
 # MIT License
 
-Copyright (c) 2025 Posit Software, PBC
+Copyright (c) 2026 Posit Software, PBC
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

querychat-0.4.0/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: querychat
+Version: 0.4.0
+Summary: Chat with your data using natural language
+Project-URL: Homepage, https://github.com/posit-dev/querychat
+Project-URL: Repository, https://github.com/posit-dev/querychat
+Project-URL: Issues, https://github.com/posit-dev/querychat/issues
+Project-URL: Source, https://github.com/posit-dev/querychat/tree/main/pkg-py
+Author-email: Joe Cheng <joe@posit.co>, Garrick Aden-Buie <garrick@posit.co>, Carson Sievert <carson@posit.co>, Dan Chen <daniel.chen@posit.co>, Barret Schloerke <barret@posit.co>
+Maintainer-email: Garrick Aden-Buie <garrick@posit.co>
+License: # MIT License
+        
+        Copyright (c) 2026 Posit Software, PBC
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE.md
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
+Requires-Dist: chatlas>=0.13.2
+Requires-Dist: chevron
+Requires-Dist: duckdb
+Requires-Dist: great-tables>=0.16.0
+Requires-Dist: htmltools
+Requires-Dist: narwhals
+Requires-Dist: shiny>=1.5.1
+Requires-Dist: shinychat>=0.2.8
+Requires-Dist: sqlalchemy>=2.0.0
+Provides-Extra: pandas
+Requires-Dist: pandas; extra == 'pandas'
+Provides-Extra: polars
+Requires-Dist: polars; extra == 'polars'
+Description-Content-Type: text/markdown
+
+# querychat <a href="https://posit-dev.github.io/querychat/py/"><img src="https://posit-dev.github.io/querychat/images/querychat.png" align="right" height="138" alt="querychat website" /></a>
+
+<p>
+<!-- badges start -->
+<a href="https://pypi.org/project/querychat/"><img alt="PyPI" src="https://img.shields.io/pypi/v/querychat?logo=python&logoColor=white&color=orange"></a>
+<a href="https://choosealicense.com/licenses/mit/"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="MIT License"></a>
+<a href="https://pypi.org/project/querychat"><img src="https://img.shields.io/pypi/pyversions/querychat.svg" alt="versions"></a>
+<a href="https://github.com/posit-dev/querychat"><img src="https://github.com/posit-dev/querychat/actions/workflows/test.yml/badge.svg?branch=main" alt="Python Tests"></a>
+<!-- badges end -->
+</p>
+
+
+QueryChat facilitates safe and reliable natural language exploration of tabular data, powered by SQL and large language models (LLMs). For analysts, it offers an intuitive web application where they can quickly ask questions of their data and receive verifiable data-driven answers. For software developers, QueryChat provides a comprehensive Python API to access core functionality -- including chat UI, generated SQL statements, resulting data, and more. This capability enables the seamless integration of natural language querying into bespoke data applications.
+
+## Installation
+
+Install the latest stable release [from PyPI](https://pypi.org/project/querychat/):
+
+```bash
+pip install querychat
+```
+
+## Quick start
+
+The main entry point is the [`QueryChat` class](https://posit-dev.github.io/querychat/py/reference/QueryChat.html). It requires a [data source](https://posit-dev.github.io/querychat/py/data-sources.html) (e.g., pandas, polars, etc) and a name for the data.
+
+```python
+from querychat import QueryChat
+from querychat.data import titanic
+
+qc = QueryChat(titanic(), "titanic")
+app = qc.app()
+# app.run()
+```
+
+<p align="center">
+  <img src="docs/images/quickstart.png" alt="QueryChat interface showing natural language queries" width="85%">
+</p>
+
+## Custom apps
+
+Build your own custom web apps with natural language querying capabilities, such as [this one](https://github.com/posit-conf-2025/llm/blob/main/_solutions/25_querychat/25_querychat_02-end-app.R) which provides a bespoke interface for exploring Airbnb listings:
+
+<p align="center">
+  <img src="docs/images/airbnb.png" alt="A custom app for exploring Airbnb listings, powered by QueryChat." width="85%">
+</p>
+
+## Learn more
+
+See the [website](https://posit-dev.github.io/querychat/py) to learn more.

{querychat-0.3.0 → querychat-0.4.0}/pkg-py/LICENSE

@@ -1,6 +1,6 @@
 # MIT License
 
-Copyright (c) 2025 Posit Software, PBC
+Copyright (c) 2026 Posit Software, PBC
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

querychat-0.4.0/pkg-py/README.md

@@ -0,0 +1,50 @@
+# querychat <a href="https://posit-dev.github.io/querychat/py/"><img src="https://posit-dev.github.io/querychat/images/querychat.png" align="right" height="138" alt="querychat website" /></a>
+
+<p>
+<!-- badges start -->
+<a href="https://pypi.org/project/querychat/"><img alt="PyPI" src="https://img.shields.io/pypi/v/querychat?logo=python&logoColor=white&color=orange"></a>
+<a href="https://choosealicense.com/licenses/mit/"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="MIT License"></a>
+<a href="https://pypi.org/project/querychat"><img src="https://img.shields.io/pypi/pyversions/querychat.svg" alt="versions"></a>
+<a href="https://github.com/posit-dev/querychat"><img src="https://github.com/posit-dev/querychat/actions/workflows/test.yml/badge.svg?branch=main" alt="Python Tests"></a>
+<!-- badges end -->
+</p>
+
+
+QueryChat facilitates safe and reliable natural language exploration of tabular data, powered by SQL and large language models (LLMs). For analysts, it offers an intuitive web application where they can quickly ask questions of their data and receive verifiable data-driven answers. For software developers, QueryChat provides a comprehensive Python API to access core functionality -- including chat UI, generated SQL statements, resulting data, and more. This capability enables the seamless integration of natural language querying into bespoke data applications.
+
+## Installation
+
+Install the latest stable release [from PyPI](https://pypi.org/project/querychat/):
+
+```bash
+pip install querychat
+```
+
+## Quick start
+
+The main entry point is the [`QueryChat` class](https://posit-dev.github.io/querychat/py/reference/QueryChat.html). It requires a [data source](https://posit-dev.github.io/querychat/py/data-sources.html) (e.g., pandas, polars, etc) and a name for the data.
+
+```python
+from querychat import QueryChat
+from querychat.data import titanic
+
+qc = QueryChat(titanic(), "titanic")
+app = qc.app()
+# app.run()
+```
+
+<p align="center">
+  <img src="docs/images/quickstart.png" alt="QueryChat interface showing natural language queries" width="85%">
+</p>
+
+## Custom apps
+
+Build your own custom web apps with natural language querying capabilities, such as [this one](https://github.com/posit-conf-2025/llm/blob/main/_solutions/25_querychat/25_querychat_02-end-app.R) which provides a bespoke interface for exploring Airbnb listings:
+
+<p align="center">
+  <img src="docs/images/airbnb.png" alt="A custom app for exploring Airbnb listings, powered by QueryChat." width="85%">
+</p>
+
+## Learn more
+
+See the [website](https://posit-dev.github.io/querychat/py) to learn more.

{querychat-0.3.0 → querychat-0.4.0}/pkg-py/src/querychat/_datasource.py

@@ -5,15 +5,20 @@ from typing import TYPE_CHECKING
 
 import duckdb
 import narwhals.stable.v1 as nw
-import pandas as pd
 from sqlalchemy import inspect, text
 from sqlalchemy.sql import sqltypes
 
+from ._df_compat import duckdb_result_to_nw, read_sql
+from ._utils import check_query
+
 if TYPE_CHECKING:
-    from narwhals.stable.v1.typing import IntoFrame
     from sqlalchemy.engine import Connection, Engine
 
 
+class MissingColumnsError(ValueError):
+    """Raised when a query result is missing required columns."""
+
+
 class DataSource(ABC):
     """
     An abstract class defining the interface for data sources used by QueryChat.
@@ -53,7 +58,7 @@ class DataSource(ABC):
         ...
 
     @abstractmethod
-    def execute_query(self, query: str) -> pd.DataFrame:
+    def execute_query(self, query: str) -> nw.DataFrame:
         """
         Execute SQL query and return results as DataFrame.
 
@@ -65,20 +70,48 @@ class DataSource(ABC):
         Returns
         -------
         :
-            Query results as a pandas DataFrame
+            Query results as a narwhals DataFrame
 
         """
         ...
 
     @abstractmethod
-    def get_data(self) -> pd.DataFrame:
+    def test_query(
+        self, query: str, *, require_all_columns: bool = False
+    ) -> nw.DataFrame:
+        """
+        Test SQL query by fetching only one row.
+
+        Parameters
+        ----------
+        query
+            SQL query to test
+        require_all_columns
+            If True, validates that result includes all original table columns.
+            Additional computed columns are allowed.
+
+        Returns
+        -------
+        :
+            Query results as a narwhals DataFrame with at most one row
+
+        Raises
+        ------
+        MissingColumnsError
+            If require_all_columns is True and result is missing required columns
+
+        """
+        ...
+
+    @abstractmethod
+    def get_data(self) -> nw.DataFrame:
         """
         Return the unfiltered data as a DataFrame.
 
         Returns
         -------
         :
-            The complete dataset as a pandas DataFrame
+            The complete dataset as a narwhals DataFrame
 
         """
         ...
@@ -99,27 +132,44 @@ class DataSource(ABC):
 
 
 class DataFrameSource(DataSource):
-    """A DataSource implementation that wraps a pandas DataFrame using DuckDB."""
+    """A DataSource implementation that wraps a DataFrame using DuckDB."""
 
-    _df: nw.DataFrame | nw.LazyFrame
+    _df: nw.DataFrame
 
-    def __init__(self, df: IntoFrame, table_name: str):
+    def __init__(self, df: nw.DataFrame, table_name: str):
         """
-        Initialize with a pandas DataFrame.
+        Initialize with a DataFrame.
 
         Parameters
         ----------
         df
-            The DataFrame to wrap
+            The DataFrame to wrap (pandas, polars, or any narwhals-compatible frame)
         table_name
             Name of the table in SQL queries
 
         """
-        self._conn = duckdb.connect(database=":memory:")
-        self._df = nw.from_native(df)
+        self._df = nw.from_native(df) if not isinstance(df, nw.DataFrame) else df
         self.table_name = table_name
-        # TODO(@gadenbuie): If the data frame is already SQL-backed, maybe we shouldn't be making a new copy here.
-        self._conn.register(table_name, self._df.lazy().collect().to_pandas())
+
+        self._conn = duckdb.connect(database=":memory:")
+        self._conn.register(table_name, self._df.to_native())
+        self._conn.execute("""
+-- extensions: lock down supply chain + auto behaviors
+SET allow_community_extensions = false;
+SET allow_unsigned_extensions = false;
+SET autoinstall_known_extensions = false;
+SET autoload_known_extensions = false;
+
+-- external I/O: block file/database/network access from SQL
+SET enable_external_access = false;
+SET disabled_filesystems = 'LocalFileSystem';
+
+-- freeze configuration so user SQL can't relax anything
+SET lock_configuration = true;
+        """)
+
+        # Store original column names for validation
+        self._colnames = list(self._df.columns)
 
     def get_db_type(self) -> str:
         """
@@ -151,16 +201,8 @@ class DataFrameSource(DataSource):
         """
         schema = [f"Table: {self.table_name}", "Columns:"]
 
-        # Ensure we're working with a DataFrame, not a LazyFrame
-        ndf = (
-            self._df.head(10).collect()
-            if isinstance(self._df, nw.LazyFrame)
-            else self._df
-        )
-
-        for column in ndf.columns:
-            # Map pandas dtypes to SQL-like types
-            dtype = ndf[column].dtype
+        for column in self._df.columns:
+            dtype = self._df[column].dtype
             if dtype.is_integer():
                 sql_type = "INTEGER"
             elif dtype.is_float():
@@ -176,17 +218,14 @@ class DataFrameSource(DataSource):
 
             column_info = [f"- {column} ({sql_type})"]
 
-            # For TEXT columns, check if they're categorical
             if sql_type == "TEXT":
-                unique_values = ndf[column].drop_nulls().unique()
+                unique_values = self._df[column].drop_nulls().unique()
                 if unique_values.len() <= categorical_threshold:
                     categories = unique_values.to_list()
                     categories_str = ", ".join([f"'{c}'" for c in categories])
                     column_info.append(f"  Categorical values: {categories_str}")
-
-            # For numeric columns, include range
             elif sql_type in ["INTEGER", "FLOAT", "DATE", "TIME"]:
-                rng = ndf[column].min(), ndf[column].max()
+                rng = self._df[column].min(), self._df[column].max()
                 if rng[0] is None and rng[1] is None:
                     column_info.append("  Range: NULL to NULL")
                 else:
@@ -196,10 +235,12 @@ class DataFrameSource(DataSource):
 
         return "\n".join(schema)
 
-    def execute_query(self, query: str) -> pd.DataFrame:
+    def execute_query(self, query: str) -> nw.DataFrame:
         """
         Execute query using DuckDB.
 
+        Uses polars if available, otherwise falls back to pandas.
+
         Parameters
         ----------
         query
@@ -208,23 +249,73 @@ class DataFrameSource(DataSource):
         Returns
         -------
         :
-            Query results as pandas DataFrame
+            Query results as narwhals DataFrame
+
+        Raises
+        ------
+        UnsafeQueryError
+            If the query starts with a disallowed SQL operation
 
         """
-        return self._conn.execute(query).df()
+        check_query(query)
+        return duckdb_result_to_nw(self._conn.execute(query))
 
-    def get_data(self) -> pd.DataFrame:
+    def test_query(
+        self, query: str, *, require_all_columns: bool = False
+    ) -> nw.DataFrame:
+        """
+        Test query by fetching only one row.
+
+        Parameters
+        ----------
+        query
+            SQL query to test
+        require_all_columns
+            If True, validates that result includes all original table columns
+
+        Returns
+        -------
+        :
+            Query results with at most one row
+
+        Raises
+        ------
+        UnsafeQueryError
+            If the query starts with a disallowed SQL operation
+        MissingColumnsError
+            If require_all_columns is True and result is missing required columns
+
+        """
+        check_query(query)
+        result = duckdb_result_to_nw(self._conn.execute(f"{query} LIMIT 1"))
+
+        if require_all_columns:
+            result_columns = set(result.columns)
+            original_columns_set = set(self._colnames)
+            missing_columns = original_columns_set - result_columns
+
+            if missing_columns:
+                missing_list = ", ".join(f"'{col}'" for col in sorted(missing_columns))
+                original_list = ", ".join(f"'{col}'" for col in self._colnames)
+                raise MissingColumnsError(
+                    f"Query result missing required columns: {missing_list}. "
+                    f"The query must return all original table columns. "
+                    f"Original columns: {original_list}"
+                )
+
+        return result
+
+    def get_data(self) -> nw.DataFrame:
         """
         Return the unfiltered data as a DataFrame.
 
         Returns
         -------
         :
-            The complete dataset as a pandas DataFrame
+            The complete dataset as a narwhals DataFrame
 
         """
-        # TODO(@gadenbuie): This should just return `self._df` and not a pandas DataFrame
-        return self._df.lazy().collect().to_pandas()
+        return self._df
 
     def cleanup(self) -> None:
         """
@@ -268,6 +359,10 @@ class SQLAlchemySource(DataSource):
         if not inspector.has_table(table_name):
             raise ValueError(f"Table '{table_name}' not found in database")
 
+        # Store original column names for validation
+        columns_info = inspector.get_columns(table_name)
+        self._colnames = [col["name"] for col in columns_info]
+
     def get_db_type(self) -> str:
         """
         Get the database type.
@@ -412,10 +507,12 @@ class SQLAlchemySource(DataSource):
 
         return "\n".join(schema)
 
-    def execute_query(self, query: str) -> pd.DataFrame:
+    def execute_query(self, query: str) -> nw.DataFrame:
         """
         Execute SQL query and return results as DataFrame.
 
+        Uses polars if available, otherwise falls back to pandas.
+
         Parameters
         ----------
         query
@@ -424,20 +521,80 @@ class SQLAlchemySource(DataSource):
         Returns
         -------
         :
-            Query results as pandas DataFrame
+            Query results as narwhals DataFrame
+
+        Raises
+        ------
+        UnsafeQueryError
+            If the query starts with a disallowed SQL operation
+
+        """
+        check_query(query)
+        with self._get_connection() as conn:
+            return read_sql(text(query), conn)
+
+    def test_query(
+        self, query: str, *, require_all_columns: bool = False
+    ) -> nw.DataFrame:
+        """
+        Test query by fetching only one row.
+
+        Parameters
+        ----------
+        query
+            SQL query to test
+        require_all_columns
+            If True, validates that result includes all original table columns
+
+        Returns
+        -------
+        :
+            Query results with at most one row
+
+        Raises
+        ------
+        UnsafeQueryError
+            If the query starts with a disallowed SQL operation
+        MissingColumnsError
+            If require_all_columns is True and result is missing required columns
 
         """
+        check_query(query)
         with self._get_connection() as conn:
-            return pd.read_sql_query(text(query), conn)
+            # Use read_sql with limit to get at most one row
+            limit_query = f"SELECT * FROM ({query}) AS subquery LIMIT 1"
+            try:
+                result = read_sql(text(limit_query), conn)
+            except Exception:
+                # If LIMIT syntax doesn't work, fall back to regular read and take first row
+                result = read_sql(text(query), conn).head(1)
+
+            if require_all_columns:
+                result_columns = set(result.columns)
+                original_columns_set = set(self._colnames)
+                missing_columns = original_columns_set - result_columns
+
+                if missing_columns:
+                    missing_list = ", ".join(
+                        f"'{col}'" for col in sorted(missing_columns)
+                    )
+                    original_list = ", ".join(f"'{col}'" for col in self._colnames)
+                    raise MissingColumnsError(
+                        f"Query result missing required columns: {missing_list}. "
+                        f"The query must return all original table columns. "
+                        f"Original columns: {original_list}"
+                    )
+
+            return result
 
-    def get_data(self) -> pd.DataFrame:
+    def get_data(self) -> nw.DataFrame:
         """
         Return the unfiltered data as a DataFrame.
 
         Returns
         -------
         :
-            The complete dataset as a pandas DataFrame
+            The complete dataset as a narwhals DataFrame
 
         """
         return self.execute_query(f"SELECT * FROM {self.table_name}")

querychat-0.4.0/pkg-py/src/querychat/_df_compat.py

@@ -0,0 +1,74 @@
+"""
+DataFrame compatibility: try polars first, fall back to pandas.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import narwhals.stable.v1 as nw
+
+if TYPE_CHECKING:
+    import duckdb
+    from sqlalchemy.engine import Connection
+    from sqlalchemy.sql.elements import TextClause
+
+_INSTALL_MSG = "Install one with: pip install polars  OR  pip install pandas"
+
+
+def read_sql(query: TextClause, conn: Connection) -> nw.DataFrame:
+    try:
+        import polars as pl  # noqa: PLC0415  # pyright: ignore[reportMissingImports]
+
+        return nw.from_native(pl.read_database(query, connection=conn))
+    except Exception:  # noqa: S110
+        # Catches ImportError for polars, and other errors (e.g., missing pyarrow)
+        # Intentional fallback to pandas - no logging needed
+        pass
+
+    try:
+        import pandas as pd  # noqa: PLC0415  # pyright: ignore[reportMissingImports]
+
+        return nw.from_native(pd.read_sql_query(query, conn))
+    except ImportError:
+        pass
+
+    raise ImportError(f"SQLAlchemySource requires 'polars' or 'pandas'. {_INSTALL_MSG}")
+
+
+def duckdb_result_to_nw(
+    result: duckdb.DuckDBPyRelation | duckdb.DuckDBPyConnection,
+) -> nw.DataFrame:
+    try:
+        return nw.from_native(result.pl())
+    except Exception:  # noqa: S110
+        # Catches ImportError for polars, and other errors (e.g., missing pyarrow)
+        # Intentional fallback to pandas - no logging needed
+        pass
+
+    try:
+        return nw.from_native(result.df())
+    except ImportError:
+        pass
+
+    raise ImportError(f"DataFrameSource requires 'polars' or 'pandas'. {_INSTALL_MSG}")
+
+
+def read_csv(path: str) -> nw.DataFrame:
+    try:
+        import polars as pl  # noqa: PLC0415  # pyright: ignore[reportMissingImports]
+
+        return nw.from_native(pl.read_csv(path))
+    except Exception:  # noqa: S110
+        # Catches ImportError for polars, and other errors (e.g., missing pyarrow)
+        # Intentional fallback to pandas - no logging needed
+        pass
+
+    try:
+        import pandas as pd  # noqa: PLC0415  # pyright: ignore[reportMissingImports]
+
+        return nw.from_native(pd.read_csv(path, compression="gzip"))
+    except ImportError:
+        pass
+
+    raise ImportError(f"Loading data requires 'polars' or 'pandas'. {_INSTALL_MSG}")