querychat 0.2.1__tar.gz → 0.3.0__tar.gz

{querychat-0.2.1 → querychat-0.3.0}/.gitignore

@@ -260,3 +260,8 @@ _dev
 .Rprofile
 renv/
 renv.lock
+
+# Claude
+.claude/settings.local.json
+
+/.luarc.json

{querychat-0.2.1 → querychat-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: querychat
-Version: 0.2.1
+Version: 0.3.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
@@ -31,20 +31,20 @@ License: # MIT License
         SOFTWARE.
 License-File: LICENSE.md
 Classifier: Programming Language :: Python
-Classifier: Programming Language :: Python :: 3.8
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
-Requires-Python: >=3.9
-Requires-Dist: chatlas
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
+Requires-Dist: chatlas>=0.13.2
 Requires-Dist: chevron
 Requires-Dist: duckdb
 Requires-Dist: htmltools
 Requires-Dist: narwhals
 Requires-Dist: pandas
-Requires-Dist: shiny
+Requires-Dist: shiny>=1.5.1
+Requires-Dist: shinychat>=0.2.8
 Requires-Dist: shinywidgets
 Requires-Dist: sqlalchemy>=2.0.0
 Description-Content-Type: text/markdown

querychat-0.3.0/pkg-py/src/querychat/__init__.py

@@ -0,0 +1,15 @@
+from ._deprecated import greeting, init, sidebar, system_prompt
+from ._deprecated import mod_server as server
+from ._deprecated import mod_ui as ui
+from ._querychat import QueryChat
+
+__all__ = (
+    "QueryChat",
+    # TODO(lifecycle): Remove these deprecated functions when we reach v1.0
+    "greeting",
+    "init",
+    "server",
+    "sidebar",
+    "system_prompt",
+    "ui",
+)

querychat-0.2.1/pkg-py/src/querychat/datasource.py → querychat-0.3.0/pkg-py/src/querychat/_datasource.py

@@ -1,94 +1,162 @@
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, ClassVar, Protocol
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
 
 import duckdb
-import narwhals as nw
+import narwhals.stable.v1 as nw
 import pandas as pd
 from sqlalchemy import inspect, text
 from sqlalchemy.sql import sqltypes
 
 if TYPE_CHECKING:
+    from narwhals.stable.v1.typing import IntoFrame
     from sqlalchemy.engine import Connection, Engine
 
 
-class DataSource(Protocol):
-    db_engine: ClassVar[str]
+class DataSource(ABC):
+    """
+    An abstract class defining the interface for data sources used by QueryChat.
+
+    Attributes
+    ----------
+    table_name
+        Name of the table to be used in SQL queries.
+
+    """
+
+    table_name: str
 
-    def get_schema(self, *, categorical_threshold) -> str:
+    @abstractmethod
+    def get_db_type(self) -> str:
+        """Name for the database behind the SQL execution."""
+        ...
+
+    @abstractmethod
+    def get_schema(self, *, categorical_threshold: int) -> str:
         """
         Return schema information about the table as a string.
 
-        Args:
-            categorical_threshold: Maximum number of unique values for a text
-                column to be considered categorical
+        Parameters
+        ----------
+        categorical_threshold
+            Maximum number of unique values for a text column to be considered
+            categorical
 
-        Returns:
+        Returns
+        -------
+        :
             A string containing the schema information in a format suitable for
             prompting an LLM about the data structure
 
         """
         ...
 
+    @abstractmethod
     def execute_query(self, query: str) -> pd.DataFrame:
         """
         Execute SQL query and return results as DataFrame.
 
-        Args:
-            query: SQL query to execute
+        Parameters
+        ----------
+        query
+            SQL query to execute
 
-        Returns:
+        Returns
+        -------
+        :
             Query results as a pandas DataFrame
 
         """
         ...
 
+    @abstractmethod
     def get_data(self) -> pd.DataFrame:
         """
         Return the unfiltered data as a DataFrame.
 
-        Returns:
+        Returns
+        -------
+        :
             The complete dataset as a pandas DataFrame
 
         """
         ...
 
+    @abstractmethod
+    def cleanup(self) -> None:
+        """
+        Clean up resources associated with the data source.
+
+        This method should clean up any connections or resources used by the
+        data source.
+
+        Returns
+        -------
+        None
+
+        """
 
-class DataFrameSource:
+
+class DataFrameSource(DataSource):
     """A DataSource implementation that wraps a pandas DataFrame using DuckDB."""
 
-    db_engine: ClassVar[str] = "DuckDB"
+    _df: nw.DataFrame | nw.LazyFrame
 
-    def __init__(self, df: pd.DataFrame, table_name: str):
+    def __init__(self, df: IntoFrame, table_name: str):
         """
         Initialize with a pandas DataFrame.
 
-        Args:
-            df: The DataFrame to wrap
-            table_name: Name of the table in SQL queries
+        Parameters
+        ----------
+        df
+            The DataFrame to wrap
+        table_name
+            Name of the table in SQL queries
 
         """
         self._conn = duckdb.connect(database=":memory:")
-        self._df = df
-        self._table_name = table_name
-        self._conn.register(table_name, df)
+        self._df = nw.from_native(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())
+
+    def get_db_type(self) -> str:
+        """
+        Get the database type.
+
+        Returns
+        -------
+        :
+            The string "DuckDB"
+
+        """
+        return "DuckDB"
 
     def get_schema(self, *, categorical_threshold: int) -> str:
         """
         Generate schema information from DataFrame.
 
-        Args:
-            table_name: Name to use for the table in schema description
-            categorical_threshold: Maximum number of unique values for a text column
-                                to be considered categorical
+        Parameters
+        ----------
+        categorical_threshold
+            Maximum number of unique values for a text column to be considered
+            categorical
 
-        Returns:
+        Returns
+        -------
+        :
             String describing the schema
 
         """
-        ndf = nw.from_native(self._df)
+        schema = [f"Table: {self.table_name}", "Columns:"]
 
-        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
@@ -132,10 +200,14 @@ class DataFrameSource:
         """
         Execute query using DuckDB.
 
-        Args:
-            query: SQL query to execute
+        Parameters
+        ----------
+        query
+            SQL query to execute
 
-        Returns:
+        Returns
+        -------
+        :
             Query results as pandas DataFrame
 
         """
@@ -145,39 +217,66 @@ class DataFrameSource:
         """
         Return the unfiltered data as a DataFrame.
 
-        Returns:
+        Returns
+        -------
+        :
             The complete dataset as a pandas DataFrame
 
         """
-        return self._df.copy()
+        # TODO(@gadenbuie): This should just return `self._df` and not a pandas DataFrame
+        return self._df.lazy().collect().to_pandas()
 
+    def cleanup(self) -> None:
+        """
+        Close the DuckDB connection.
 
-class SQLAlchemySource:
-    """
-    A DataSource implementation that supports multiple SQL databases via SQLAlchemy.
+        Returns
+        -------
+        None
 
-    Supports various databases including PostgreSQL, MySQL, SQLite, Snowflake, and Databricks.
+        """
+        if self._conn:
+            self._conn.close()
+
+
+class SQLAlchemySource(DataSource):
     """
+    A DataSource implementation that supports multiple SQL databases via
+    SQLAlchemy.
 
-    db_engine: ClassVar[str] = "SQLAlchemy"
+    Supports various databases including PostgreSQL, MySQL, SQLite, Snowflake,
+    and Databricks.
+    """
 
     def __init__(self, engine: Engine, table_name: str):
         """
         Initialize with a SQLAlchemy engine.
 
-        Args:
-            engine: SQLAlchemy engine
-            table_name: Name of the table to query
+        Parameters
+        ----------
+        engine
+            SQLAlchemy engine
+        table_name
+            Name of the table to query
 
         """
         self._engine = engine
-        self._table_name = table_name
+        self.table_name = table_name
 
         # Validate table exists
         inspector = inspect(self._engine)
         if not inspector.has_table(table_name):
             raise ValueError(f"Table '{table_name}' not found in database")
 
+    def get_db_type(self) -> str:
+        """
+        Get the database type.
+
+        Returns the specific database type (e.g., POSTGRESQL, MYSQL, SQLITE) by
+        inspecting the SQLAlchemy engine. Removes " SQL" suffix if present.
+        """
+        return self._engine.dialect.name.upper().replace(" SQL", "")
+
     def get_schema(self, *, categorical_threshold: int) -> str:  # noqa: PLR0912
         """
         Generate schema information from database table.
@@ -187,9 +286,9 @@ class SQLAlchemySource:
 
         """
         inspector = inspect(self._engine)
-        columns = inspector.get_columns(self._table_name)
+        columns = inspector.get_columns(self.table_name)
 
-        schema = [f"Table: {self._table_name}", "Columns:"]
+        schema = [f"Table: {self.table_name}", "Columns:"]
 
         # Build a single query to get all column statistics
         select_parts = []
@@ -236,13 +335,13 @@ class SQLAlchemySource:
         if select_parts:
             try:
                 stats_query = text(
-                    f"SELECT {', '.join(select_parts)} FROM {self._table_name}",
+                    f"SELECT {', '.join(select_parts)} FROM {self.table_name}",
                 )
                 with self._get_connection() as conn:
                     result = conn.execute(stats_query).fetchone()
                     if result:
                         # Convert result to dict for easier access
-                        column_stats = dict(zip(result._fields, result))
+                        column_stats = dict(zip(result._fields, result, strict=False))
             except Exception:  # noqa: S110
                 pass  # Fall back to no statistics if query fails
 
@@ -264,7 +363,7 @@ class SQLAlchemySource:
                 # Build UNION query for all categorical columns
                 union_parts = [
                     f"SELECT '{col_name}' as column_name, {col_name} as value "
-                    f"FROM {self._table_name} WHERE {col_name} IS NOT NULL "
+                    f"FROM {self.table_name} WHERE {col_name} IS NOT NULL "
                     f"GROUP BY {col_name}"
                     for col_name in text_cols_to_query
                 ]
@@ -317,10 +416,14 @@ class SQLAlchemySource:
         """
         Execute SQL query and return results as DataFrame.
 
-        Args:
-            query: SQL query to execute
+        Parameters
+        ----------
+        query
+            SQL query to execute
 
-        Returns:
+        Returns
+        -------
+        :
             Query results as pandas DataFrame
 
         """
@@ -331,11 +434,13 @@ class SQLAlchemySource:
         """
         Return the unfiltered data as a DataFrame.
 
-        Returns:
+        Returns
+        -------
+        :
             The complete dataset as a pandas DataFrame
 
         """
-        return self.execute_query(f"SELECT * FROM {self._table_name}")
+        return self.execute_query(f"SELECT * FROM {self.table_name}")
 
     def _get_sql_type_name(self, type_: sqltypes.TypeEngine) -> str:  # noqa: PLR0911
         """Convert SQLAlchemy type to SQL type name."""
@@ -361,3 +466,15 @@ class SQLAlchemySource:
     def _get_connection(self) -> Connection:
         """Get a connection to use for queries."""
         return self._engine.connect()
+
+    def cleanup(self) -> None:
+        """
+        Dispose of the SQLAlchemy engine.
+
+        Returns
+        -------
+        None
+
+        """
+        if self._engine:
+            self._engine.dispose()

querychat-0.3.0/pkg-py/src/querychat/_deprecated.py

@@ -0,0 +1,108 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Optional, Union
+
+from shiny import Inputs, Outputs, Session, module, ui
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    import chatlas
+    import sqlalchemy
+    from narwhals.stable.v1.typing import IntoFrame
+
+    from ._datasource import DataSource
+
+
+def init(
+    data_source: IntoFrame | sqlalchemy.Engine,
+    table_name: str,
+    *,
+    greeting: Optional[str | Path] = None,
+    data_description: Optional[str | Path] = None,
+    extra_instructions: Optional[str | Path] = None,
+    prompt_template: Optional[str | Path] = None,
+    system_prompt_override: Optional[str] = None,
+    client: Optional[Union[chatlas.Chat, str]] = None,
+):
+    """
+    Initialize querychat with any compliant data source.
+
+    **Deprecated.** Use `QueryChat()` instead.
+    """
+    raise RuntimeError("init() is deprecated. Use QueryChat() instead.")
+
+
+@module.ui
+def mod_ui(**kwargs) -> ui.TagList:
+    """
+    Create the UI for the querychat component.
+
+    **Deprecated.** Use `QueryChat.ui()` instead.
+    """
+    raise RuntimeError("mod_ui() is deprecated. Use QueryChat.ui() instead.")
+
+
+@module.server
+def mod_server(
+    input: Inputs,
+    output: Outputs,
+    session: Session,
+    querychat_config: Any,
+):
+    """
+    Initialize the querychat server.
+
+    **Deprecated.** Use `QueryChat.server()` instead.
+    """
+    raise RuntimeError("mod_server() is deprecated. Use QueryChat.server() instead.")
+
+
+def sidebar(
+    id: str,
+    width: int = 400,
+    height: str = "100%",
+    **kwargs,
+) -> ui.Sidebar:
+    """
+    Create a sidebar containing the querychat UI.
+
+    **Deprecated.** Use `QueryChat.sidebar()` instead.
+    """
+    raise RuntimeError("sidebar() is deprecated. Use QueryChat.sidebar() instead.")
+
+
+def system_prompt(
+    data_source: DataSource,
+    *,
+    data_description: Optional[str | Path] = None,
+    extra_instructions: Optional[str | Path] = None,
+    categorical_threshold: int = 20,
+    prompt_template: Optional[str | Path] = None,
+) -> str:
+    """
+    Create a system prompt for the chat model based on a data source's schema
+    and optional additional context and instructions.
+
+    **Deprecated.** Use `QueryChat.set_system_prompt()` instead.
+    """
+    raise RuntimeError(
+        "system_prompt() is deprecated. Use QueryChat.set_system_prompt() instead."
+    )
+
+
+def greeting(
+    querychat_config,
+    *,
+    generate: bool = True,
+    stream: bool = False,
+    **kwargs,
+) -> str | None:
+    """
+    Generate or retrieve a greeting message.
+
+    **Deprecated.** Use `QueryChat.generate_greeting()` instead.
+    """
+    raise RuntimeError(
+        "greeting() is deprecated. Use QueryChat.generate_greeting() instead."
+    )

querychat-0.3.0/pkg-py/src/querychat/_icons.py

@@ -0,0 +1,20 @@
+from typing import Literal
+
+from shiny import ui
+
+ICON_NAMES = Literal["arrow-counterclockwise", "funnel-fill", "terminal-fill", "table"]
+
+
+def bs_icon(name: ICON_NAMES) -> ui.HTML:
+    """Get Bootstrap icon SVG by name."""
+    if name not in BS_ICONS:
+        raise ValueError(f"Unknown Bootstrap icon: {name}")
+    return ui.HTML(BS_ICONS[name])
+
+
+BS_ICONS = {
+    "arrow-counterclockwise": '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" class="bi bi-arrow-counterclockwise" style="height:1em;width:1em;fill:currentColor;vertical-align:-0.125em;" aria-hidden="true" role="img"><path fill-rule="evenodd" d="M8 3a5 5 0 1 1-4.546 2.914.5.5 0 0 0-.908-.417A6 6 0 1 0 8 2v1z"></path><path d="M8 4.466V.534a.25.25 0 0 0-.41-.192L5.23 2.308a.25.25 0 0 0 0 .384l2.36 1.966A.25.25 0 0 0 8 4.466z"></path></svg>',
+    "funnel-fill": '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" class="bi bi-funnel-fill" viewBox="0 0 16 16"><path d="M1.5 1.5A.5.5 0 0 1 2 1h12a.5.5 0 0 1 .5.5v2a.5.5 0 0 1-.128.334L10 8.692V13.5a.5.5 0 0 1-.342.474l-3 1A.5.5 0 0 1 6 14.5V8.692L1.628 3.834A.5.5 0 0 1 1.5 3.5z"/></svg>',
+    "terminal-fill": '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" class="bi bi-terminal-fill " style="height:1em;width:1em;fill:currentColor;vertical-align:-0.125em;" aria-hidden="true" role="img" ><path d="M0 3a2 2 0 0 1 2-2h12a2 2 0 0 1 2 2v10a2 2 0 0 1-2 2H2a2 2 0 0 1-2-2V3zm9.5 5.5h-3a.5.5 0 0 0 0 1h3a.5.5 0 0 0 0-1zm-6.354-.354a.5.5 0 1 0 .708.708l2-2a.5.5 0 0 0 0-.708l-2-2a.5.5 0 1 0-.708.708L4.793 6.5 3.146 8.146z"></path></svg>',
+    "table": '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" class="bi bi-table " style="height:1em;width:1em;fill:currentColor;vertical-align:-0.125em;" aria-hidden="true" role="img" ><path d="M0 2a2 2 0 0 1 2-2h12a2 2 0 0 1 2 2v12a2 2 0 0 1-2 2H2a2 2 0 0 1-2-2V2zm15 2h-4v3h4V4zm0 4h-4v3h4V8zm0 4h-4v3h3a1 1 0 0 0 1-1v-2zm-5 3v-3H6v3h4zm-5 0v-3H1v2a1 1 0 0 0 1 1h3zm-4-4h4V8H1v3zm0-4h4V4H1v3zm5-3v3h4V4H6zm4 4H6v3h4V8z"></path></svg>',
+}