feat: Allow deferred chat client initialization

pkg-py/CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### New features
+
+* `QueryChat()` now supports deferred chat client initialization. Pass `client=` to `server()` to provide a session-scoped chat client, enabling use cases where API credentials are only available at session time (e.g., Posit Connect managed OAuth tokens). When no `client` is specified anywhere, querychat resolves a sensible default from the `QUERYCHAT_CLIENT` environment variable (or `"openai"`). (#205)
+
 ### Improvements
 
 * When a custom `prompt_template` is provided that doesn't contain Mustache references to `{{schema}}`, the expensive `get_schema()` call is now skipped entirely. This allows users with large databases to avoid slow startup by providing their own prompt that includes schema information inline (or omits it). (#208)

pkg-py/docs/build.qmd

@@ -154,6 +154,8 @@ app = App(app_ui, server)
 
 </details>
 
+If your chat client also depends on session-scoped credentials, you can defer that too by passing it to `qc.server(client=...)` alongside the `data_source`.
+
 :::
 
 :::

pkg-py/src/querychat/_querychat_base.py

@@ -81,11 +81,7 @@ def __init__(
         self._extra_instructions = extra_instructions
         self._categorical_threshold = categorical_threshold
 
-        # Normalize and initialize client (doesn't need data_source)
-        client = normalize_client(client)
-        self._client = copy.deepcopy(client)
-        self._client.set_turns([])
-
+        self._client_spec: str | chatlas.Chat | None = client
         self._client_console = None
 
         # Initialize data source (may be None for deferred pattern)
@@ -114,7 +110,6 @@ def _build_system_prompt(self) -> None:
             extra_instructions=self._extra_instructions,
             categorical_threshold=self._categorical_threshold,
         )
-        self._client.system_prompt = self._system_prompt.render(self.tools)
 
     def _require_data_source(self, method_name: str) -> DataSource[IntoFrameT]:
         """Raise if data_source is not set, otherwise return it for type narrowing."""
@@ -126,6 +121,39 @@ def _require_data_source(self, method_name: str) -> DataSource[IntoFrameT]:
             )
         return self._data_source
 
+    def _create_session_client(
+        self,
+        *,
+        client_spec: str | chatlas.Chat | None | MISSING_TYPE = MISSING,
+        tools: TOOL_GROUPS | tuple[TOOL_GROUPS, ...] | None | MISSING_TYPE = MISSING,
+        update_dashboard: Callable[[UpdateDashboardData], None] | None = None,
+        reset_dashboard: Callable[[], None] | None = None,
+    ) -> chatlas.Chat:
+        """Create a fresh, fully-configured Chat."""
+        spec = self._client_spec if isinstance(client_spec, MISSING_TYPE) else client_spec
+        chat = create_client(spec)
+
+        resolved_tools = normalize_tools(tools, default=self.tools)
+
+        if self._system_prompt is not None:
+            chat.system_prompt = self._system_prompt.render(resolved_tools)
+
+        if resolved_tools is None:
+            return chat
+
+        data_source = self._require_data_source("_create_session_client")
+
+        if "update" in resolved_tools:
+            update_fn = update_dashboard or (lambda _: None)
+            reset_fn = reset_dashboard or (lambda: None)
+            chat.register_tool(tool_update_dashboard(data_source, update_fn))
+            chat.register_tool(tool_reset_dashboard(reset_fn))
+
+        if "query" in resolved_tools:
+            chat.register_tool(tool_query(data_source))
+
+        return chat
+
     def client(
         self,
         *,
@@ -151,35 +179,20 @@ def client(
             A configured chat client.
 
         """
-        data_source = self._require_data_source("client")
-        if self._system_prompt is None:
-            raise RuntimeError("System prompt not initialized")
-        tools = normalize_tools(tools, default=self.tools)
-
-        chat = copy.deepcopy(self._client)
-        chat.set_turns([])
-        chat.system_prompt = self._system_prompt.render(tools)
-
-        if tools is None:
-            return chat
-
-        if "update" in tools:
-            update_fn = update_dashboard or (lambda _: None)
-            reset_fn = reset_dashboard or (lambda: None)
-            chat.register_tool(tool_update_dashboard(data_source, update_fn))
-            chat.register_tool(tool_reset_dashboard(reset_fn))
-
-        if "query" in tools:
-            chat.register_tool(tool_query(data_source))
-
-        return chat
+        self._require_data_source("client")
+        return self._create_session_client(
+            tools=tools,
+            update_dashboard=update_dashboard,
+            reset_dashboard=reset_dashboard,
+        )
 
     def generate_greeting(self, *, echo: Literal["none", "output"] = "none") -> str:
         """Generate a welcome greeting for the chat."""
         self._require_data_source("generate_greeting")
-        client = copy.deepcopy(self._client)
-        client.set_turns([])
-        return str(client.chat(GREETING_PROMPT, echo=echo))
+        chat = create_client(self._client_spec)
+        if self._system_prompt is not None:
+            chat.system_prompt = self._system_prompt.render(self.tools)
+        return str(chat.chat(GREETING_PROMPT, echo=echo))
 
     def console(
         self,
@@ -190,8 +203,6 @@ def console(
     ) -> None:
         """Launch an interactive console chat with the data."""
         self._require_data_source("console")
-        tools = normalize_tools(tools, default=("query",))
-
         if new or self._client_console is None:
             self._client_console = self.client(tools=tools, **kwargs)
 
@@ -262,17 +273,21 @@ def normalize_data_source(
     )
 
 
-def normalize_client(client: str | chatlas.Chat | None) -> chatlas.Chat:
+def create_client(client: str | chatlas.Chat | None) -> chatlas.Chat:
+    """Resolve a client spec into a fresh Chat with no conversation history."""
     if client is None:
         client = os.getenv("QUERYCHAT_CLIENT", None)
 
     if client is None:
         client = "openai"
 
     if isinstance(client, chatlas.Chat):
-        return client
+        chat = copy.deepcopy(client)
+    else:
+        chat = chatlas.ChatAuto(provider_model=client)
 
-    return chatlas.ChatAuto(provider_model=client)
+    chat.set_turns([])
+    return chat
 
 
 def normalize_tools(

pkg-py/src/querychat/_shiny.py

@@ -12,7 +12,7 @@
 from ._icons import bs_icon
 from ._querychat_base import TOOL_GROUPS, QueryChatBase
 from ._shiny_module import ServerValues, mod_server, mod_ui
-from ._utils import as_narwhals
+from ._utils import MISSING, MISSING_TYPE, as_narwhals
 
 if TYPE_CHECKING:
     from pathlib import Path
@@ -299,7 +299,7 @@ def app_server(input: Inputs, output: Outputs, session: Session):
                 self.id,
                 data_source=data_source,
                 greeting=self.greeting,
-                client=self._client,
+                client=self._create_session_client,
                 enable_bookmarking=enable_bookmarking,
             )
 
@@ -405,6 +405,7 @@ def server(
         self,
         *,
         data_source: Optional[IntoFrame | sqlalchemy.Engine | ibis.Table] = None,
+        client: str | chatlas.Chat | MISSING_TYPE = MISSING,
         enable_bookmarking: bool = False,
         id: Optional[str] = None,
     ) -> ServerValues[IntoFrameT]:
@@ -422,6 +423,12 @@ def server(
             Optional data source to use. If provided, sets the data_source property
             before initializing server logic. This is useful for the deferred pattern
             where data_source is not known at initialization time.
+        client
+            Optional chat client to use for this session. If provided, overrides
+            any client set at initialization time for this call only. This is useful
+            for the deferred pattern where the client cannot be created at
+            initialization time (e.g., when using Posit Connect managed OAuth
+            credentials that require session access).
         enable_bookmarking
             Whether to enable bookmarking for the querychat module.
         id
@@ -486,12 +493,18 @@ def title():
             self.data_source = data_source
 
         resolved_data_source = self._require_data_source("server")
+        resolved_client_spec = self._client_spec if isinstance(client, MISSING_TYPE) else client
+
+        def create_session_client(**kwargs) -> chatlas.Chat:
+            return self._create_session_client(
+                client_spec=resolved_client_spec, **kwargs
+            )
 
         return mod_server(
             id or self.id,
             data_source=resolved_data_source,
             greeting=self.greeting,
-            client=self.client,
+            client=create_session_client,
             enable_bookmarking=enable_bookmarking,
         )
 
@@ -728,7 +741,7 @@ def __init__(
             self.id,
             data_source=self._data_source,
             greeting=self.greeting,
-            client=self._client,
+            client=self._create_session_client,
             enable_bookmarking=enable,
         )
 

pkg-py/src/querychat/_shiny_module.py

@@ -78,14 +78,16 @@ class ServerValues(Generic[IntoFrameT]):
     client
         The session-specific chat client instance. This is a deep copy of the
         base client configured for this specific session, containing the chat
-        history and tool registrations for this session only.
+        history and tool registrations for this session only. This may be
+        `None` during stub sessions when the client depends on deferred,
+        session-scoped state.
 
     """
 
     df: Callable[[], IntoFrameT]
     sql: ReactiveStringOrNone
     title: ReactiveStringOrNone
-    client: chatlas.Chat
+    client: chatlas.Chat | None
 
 
 @module.server
@@ -115,7 +117,7 @@ def _stub_df():
             df=_stub_df,
             sql=sql,
             title=title,
-            client=client if isinstance(client, chatlas.Chat) else client(),
+            client=client if isinstance(client, chatlas.Chat) else None,
         )
 
     # Real session requires data_source

pkg-py/tests/test_base.py

@@ -10,7 +10,7 @@
 from querychat._datasource import DataFrameSource, SQLAlchemySource
 from querychat._querychat_base import (
     QueryChatBase,
-    normalize_client,
+    create_client,
     normalize_data_source,
     normalize_tools,
 )
@@ -110,26 +110,26 @@ def test_with_special_column_names(self):
 
 class TestNormalizeClient:
     def test_with_none_uses_default(self):
-        result = normalize_client(None)
+        result = create_client(None)
         assert isinstance(result, chatlas.Chat)
 
     def test_with_string_provider(self):
-        result = normalize_client("openai")
+        result = create_client("openai")
         assert isinstance(result, chatlas.Chat)
 
     def test_with_chat_instance(self):
         chat = chatlas.ChatOpenAI()
-        result = normalize_client(chat)
+        result = create_client(chat)
         assert isinstance(result, chatlas.Chat)
 
     def test_respects_env_variable(self, monkeypatch):
         monkeypatch.setenv("QUERYCHAT_CLIENT", "openai")
-        result = normalize_client(None)
+        result = create_client(None)
         assert isinstance(result, chatlas.Chat)
 
     def test_with_invalid_provider_raises(self):
         with pytest.raises(ValueError, match="is not a known chatlas provider"):
-            normalize_client("not_a_real_provider_xyz123")
+            create_client("not_a_real_provider_xyz123")
 
 
 class TestNormalizeTools:
@@ -207,9 +207,15 @@ def test_client_with_callbacks(self, sample_df):
         update_called = []
         reset_called = []
 
+        def update_dashboard(data):
+            update_called.append(data)
+
+        def reset_dashboard():
+            reset_called.append(True)
+
         client = qc.client(
-            update_dashboard=update_called.append,
-            reset_dashboard=lambda: reset_called.append(True),
+            update_dashboard=update_dashboard,
+            reset_dashboard=reset_dashboard,
         )
         assert isinstance(client, chatlas.Chat)