feat: Add new kwargs_chat attribute for persistent chat input parameters (#212)

* feat: Add new Chat(kwargs={}) parameter for persistant chat input parameters

* Improve naming, docs, and tests

* Fix test

Author: cpsievert

CHANGELOG.md

@@ -22,6 +22,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changes
 
 * `ChatOpenAI()` (and `ChatAzureOpenAI()`) move from OpenAI's Completions API to [Responses API](https://platform.openai.com/docs/api-reference/responses). If this happens to break behavior, change `ChatOpenAI()` -> `ChatOpenAICompletions()` (or `ChatAzureOpenAI()` -> `ChatAzureOpenAICompletions()`). (#192)
+* The `.set_model_params()` method no longer accepts `kwargs`. Instead, use the new `chat.kwargs_chat` attribute to set chat input parameters that persist across the chat session. (#212)
 * `Provider` implementations now require an additional `.value_tokens()` method. Previously, it was assumed that token info was logged and attached to the `Turn` as part of the `.value_turn()` method. The logging and attaching is now handled automatically. (#194)
 
 ### Improvements

chatlas/_chat.py

@@ -108,6 +108,7 @@ def __init__(
         self,
         provider: Provider,
         system_prompt: Optional[str] = None,
+        kwargs_chat: Optional[SubmitInputArgsT] = None,
     ):
         """
         Create a new chat object.
@@ -118,10 +119,17 @@ def __init__(
             A [](`~chatlas.Provider`) object.
         system_prompt
             A system prompt to set the behavior of the assistant.
+        kwargs_chat
+            Additional arguments to pass to the provider when submitting input.
+            These arguments persist across all chat interactions and will be
+            merged with any kwargs passed to individual methods like `chat()` or
+            `stream()`. They also take precedence over any parameters set via
+            `set_model_params()`.
         """
         self.provider = provider
         self._turns: list[Turn] = []
         self.system_prompt = system_prompt
+        self.kwargs_chat: SubmitInputArgsT = kwargs_chat or {}
 
         self._tools: dict[str, Tool] = {}
         self._on_tool_request_callbacks = CallbackManager()
@@ -136,7 +144,6 @@ def __init__(
 
         # Chat input parameters from `set_model_params()`
         self._standard_model_params: StandardModelParams = {}
-        self._submit_input_kwargs: Optional[SubmitInputArgsT] = None
 
     def list_models(self) -> list[ModelInfo]:
         """
@@ -1454,7 +1461,6 @@ def set_model_params(
         max_tokens: int | None | MISSING_TYPE = MISSING,
         log_probs: bool | None | MISSING_TYPE = MISSING,
         stop_sequences: list[str] | None | MISSING_TYPE = MISSING,
-        kwargs: SubmitInputArgsT | None | MISSING_TYPE = MISSING,
     ):
         """
         Set common model parameters for the chat.
@@ -1488,10 +1494,6 @@ def set_model_params(
             Include the log probabilities in the output?
         stop_sequences
             A character vector of tokens to stop generation on.
-        kwargs
-            Additional keyword arguments to use when submitting input to the
-            model. When calling this method repeatedly with different parameters,
-            only the parameters from the last call will be used.
         """
 
         params: StandardModelParams = {}
@@ -1557,13 +1559,6 @@ def set_model_params(
         # Update the standard model parameters
         self._standard_model_params.update(params)
 
-        # Update the submit input kwargs
-        if kwargs is None:
-            self._submit_input_kwargs = None
-
-        if is_present(kwargs):
-            self._submit_input_kwargs = kwargs
-
     async def register_mcp_tools_http_stream_async(
         self,
         *,
@@ -2640,8 +2635,8 @@ def _collect_all_kwargs(
         )
 
         # Add any additional kwargs provided by the user
-        if self._submit_input_kwargs:
-            all_kwargs.update(self._submit_input_kwargs)
+        if self.kwargs_chat:
+            all_kwargs.update(self.kwargs_chat)
 
         if kwargs:
             all_kwargs.update(kwargs)

tests/test_set_model_params.py

@@ -1,7 +1,9 @@
 """Tests for the set_model_params() feature."""
 
 import pytest
-from chatlas import ChatAnthropic, ChatGoogle, ChatOpenAICompletions as ChatOpenAI
+
+from chatlas import ChatAnthropic, ChatGoogle
+from chatlas import ChatOpenAICompletions as ChatOpenAI
 from chatlas._provider import StandardModelParams
 from chatlas._utils import MISSING
 
@@ -53,20 +55,6 @@ def test_set_model_params_none_reset():
     assert "top_p" in params  # Should still be there
 
 
-def test_set_model_params_kwargs():
-    """Test setting provider-specific kwargs."""
-    chat = ChatOpenAI()
-
-    chat.set_model_params(kwargs={"frequency_penalty": 0.1, "presence_penalty": 0.2})
-    kwargs = getattr(chat, "_submit_input_kwargs", {})
-    assert kwargs == {"frequency_penalty": 0.1, "presence_penalty": 0.2}
-
-    # Reset kwargs to None
-    chat.set_model_params(kwargs=None)
-    kwargs = getattr(chat, "_submit_input_kwargs", {})
-    assert kwargs is None
-
-
 def test_set_model_params_all_parameters():
     """Test setting all supported standard parameters."""
     chat = ChatOpenAI()
@@ -260,23 +248,6 @@ def test_set_model_params_updates_existing():
     assert params["top_p"] == 0.9  # New
 
 
-def test_set_model_params_kwargs_replacement():
-    """Test that kwargs are completely replaced, not merged."""
-    chat = ChatOpenAI()
-
-    # Set initial kwargs
-    chat.set_model_params(kwargs={"frequency_penalty": 0.1, "presence_penalty": 0.2})
-    kwargs = getattr(chat, "_submit_input_kwargs", {})
-    assert kwargs == {"frequency_penalty": 0.1, "presence_penalty": 0.2}
-
-    # Set new kwargs - should completely replace
-    chat.set_model_params(kwargs={"seed": 42})
-    kwargs = getattr(chat, "_submit_input_kwargs", {})
-    assert kwargs == {"seed": 42}
-    assert "frequency_penalty" not in kwargs
-    assert "presence_penalty" not in kwargs
-
-
 def test_set_model_params_invalid_temperature():
     """Test validation of temperature parameter ranges."""
     chat = ChatOpenAI()
@@ -320,7 +291,6 @@ def test_set_model_params_empty_call():
 
     # Should not change anything
     assert chat._standard_model_params == {}
-    assert chat._submit_input_kwargs is None
 
 
 def test_set_model_params_type_validation():
@@ -388,27 +358,6 @@ def test_set_model_params_reset_specific_param():
     assert params["top_p"] == 0.95
 
 
-def test_model_params_kwargs_priority():
-    """Test that submit_input_kwargs override model_params."""
-    chat = ChatOpenAI()
-
-    # Set model parameters
-    chat.set_model_params(temperature=0.1, max_tokens=100)
-
-    # Set submit input kwargs that override some model params
-    chat.set_model_params(kwargs={"temperature": 0.5, "seed": 42})
-
-    # Verify that kwargs are set correctly
-    kwargs = getattr(chat, "_submit_input_kwargs", {})
-    params = getattr(chat, "_standard_model_params", {})
-    assert kwargs["temperature"] == 0.5
-    assert kwargs["seed"] == 42
-
-    # Model params should still be stored
-    assert params["temperature"] == 0.1
-    assert params["max_tokens"] == 100
-
-
 def test_is_present_function():
     """Test the is_present helper function used in set_model_params."""
     from chatlas._chat import is_present
@@ -576,3 +525,22 @@ def test_parameter_validation_edge_cases():
 
     assert params["max_tokens"] == 1000000
     assert params["seed"] == 999999999
+
+
+def test_chat_kwargs_with_model_params():
+    """Test that Chat kwargs work alongside set_model_params."""
+    chat = ChatOpenAI()
+
+    # Set model parameters
+    chat.set_model_params(temperature=0.7, max_tokens=100)
+
+    # Set persistent chat kwargs
+    chat.kwargs_chat = {"frequency_penalty": 0.1, "presence_penalty": 0.2}
+
+    # Collect all kwargs for a chat call
+    kwargs = chat._collect_all_kwargs({"presence_penalty": 0.3})
+
+    assert kwargs.get("temperature") == 0.7
+    assert kwargs.get("max_tokens") == 100
+    assert kwargs.get("frequency_penalty") == 0.1
+    assert kwargs.get("presence_penalty") == 0.3  # Should override chat.chat_kwargs