feat(pkg-py): Add new QueryChat() API; hard deprecate old API (#101)

* feat(pkg-py): First pass at new QueryChat() API

* Update changelog

* Fix format check

* Officially deprecate old API

* Fix import lint

* Consistent wording

* Fix TypeError message

Co-authored-by: Copilot <[email protected]>

* Address feedback

* Update changelog

* Fix kwargs passed twice issue

* Hard deprecate old API; update to latest chatlas

* 3.9 typing support

* Simplify state

* Update changelog

* fix name shadowing

* Address feedback

---------

Co-authored-by: Copilot <[email protected]>

Author: cpsievert

pkg-py/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [UNRELEASED]
 
+### Changes
+
+* 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)
+
+## [UNRELEASED]
+
 ### New features
 
 * The `.sql` query and `.title` returned from `querychat.server()` are now reactive values, meaning you can now `.set()` their value, and `.df()` will update accordingly. (#98)

pkg-py/src/querychat/__init__.py

@@ -1,14 +1,15 @@
-from querychat._greeting import greeting
-from querychat.querychat import (
-    init,
-    sidebar,
-    system_prompt,
-)
-from querychat.querychat import (
-    mod_server as server,
-)
-from querychat.querychat import (
-    mod_ui as ui,
-)
+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__ = ["greeting", "init", "server", "sidebar", "system_prompt", "ui"]
+__all__ = (
+    "QueryChat",
+    # TODO(lifecycle): Remove these deprecated functions when we reach v1.0
+    "greeting",
+    "init",
+    "server",
+    "sidebar",
+    "system_prompt",
+    "ui",
+)

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 = 10,
+    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."
+    )