chatlas 0.13.1__tar.gz → 0.13.2__tar.gz

{chatlas-0.13.1 → chatlas-0.13.2}/CHANGELOG.md

@@ -7,6 +7,16 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 -->
 
+## [0.13.2] - 2025-10-02
+
+### Improvements
+
+* `ContentToolResult`'s `.get_model_value()` method now calls `.to_json(orient="record")` (instead of `.to_json()`) when relevant. As a result, if a tool call returns a Pandas `DataFrame` (or similar), the model now receives a less confusing (and smaller) JSON format. (#183)
+
+### Bug fixes
+
+* `ChatAzureOpenAI()` and `ChatDatabricks()` now work as expected when a `OPENAI_API_KEY` environment variable isn't present. (#185)
+
 ## [0.13.1] - 2025-09-18
 
 ### Bug fixes

{chatlas-0.13.1 → chatlas-0.13.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: chatlas
-Version: 0.13.1
+Version: 0.13.2
 Summary: A simple and consistent interface for chatting with LLMs
 Project-URL: Homepage, https://posit-dev.github.io/chatlas
 Project-URL: Documentation, https://posit-dev.github.io/chatlas
@@ -38,9 +38,12 @@ Requires-Dist: databricks-sdk; extra == 'dev'
 Requires-Dist: google-genai>=1.14.0; extra == 'dev'
 Requires-Dist: htmltools; extra == 'dev'
 Requires-Dist: matplotlib; extra == 'dev'
+Requires-Dist: narwhals; extra == 'dev'
 Requires-Dist: numpy>1.24.4; extra == 'dev'
 Requires-Dist: openai; extra == 'dev'
+Requires-Dist: pandas; extra == 'dev'
 Requires-Dist: pillow; extra == 'dev'
+Requires-Dist: polars; extra == 'dev'
 Requires-Dist: python-dotenv; extra == 'dev'
 Requires-Dist: ruff>=0.6.5; extra == 'dev'
 Requires-Dist: shiny; extra == 'dev'

{chatlas-0.13.1 → chatlas-0.13.2}/chatlas/_content.py

@@ -1,7 +1,9 @@
 from __future__ import annotations
 
+import inspect
+import warnings
 from pprint import pformat
-from typing import TYPE_CHECKING, Any, Literal, Optional, Union
+from typing import TYPE_CHECKING, Any, Literal, Optional, Union, cast
 
 import orjson
 from pydantic import BaseModel, ConfigDict
@@ -465,8 +467,36 @@ class ContentToolResult(Content):
 
     @staticmethod
     def _to_json(value: Any) -> object:
+        if hasattr(value, "to_pandas") and callable(value.to_pandas):
+            # Many (most?) df libs (polars, pyarrow, ...) have a .to_pandas()
+            # method, and pandas has a .to_json() method
+            value = value.to_pandas()
+
         if hasattr(value, "to_json") and callable(value.to_json):
-            return value.to_json()
+            # pandas defaults to "columns", which is not ideal for LLMs
+            # https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.to_json.html
+            sig = inspect.signature(value.to_json)
+            if "orient" in list(sig.parameters.keys()):
+                return value.to_json(orient="records")
+            else:
+                return value.to_json()
+
+        # Support for df libs (beyond those with a .to_pandas() method)
+        if hasattr(value, "__narwhals_dataframe__"):
+            try:
+                import narwhals
+
+                val = cast(narwhals.DataFrame, narwhals.from_native(value))
+                return val.to_pandas().to_json(orient="records")
+            except ImportError:
+                warnings.warn(
+                    f"Tool result object of type {type(value)} appears to be a "
+                    "narwhals-compatible DataFrame. If you run into issues with "
+                    "the LLM not understanding this value, try installing narwhals: "
+                    "`pip install narwhals`.",
+                    ImportWarning,
+                    stacklevel=2,
+                )
 
         if hasattr(value, "to_dict") and callable(value.to_dict):
             value = value.to_dict()

{chatlas-0.13.1 → chatlas-0.13.2}/chatlas/_provider_databricks.py

@@ -106,7 +106,13 @@ class DatabricksProvider(OpenAIProvider):
         import httpx
         from openai import AsyncOpenAI
 
-        super().__init__(name=name, model=model)
+        super().__init__(
+            name=name,
+            model=model,
+            # The OpenAI() constructor will fail if no API key is present.
+            # However, a dummy value is fine -- WorkspaceClient() handles the auth.
+            api_key="not-used",
+        )
 
         self._seed = None
 

{chatlas-0.13.1 → chatlas-0.13.2}/chatlas/_provider_openai.py

@@ -884,7 +884,13 @@ class OpenAIAzureProvider(OpenAIProvider):
         model: Optional[str] = "UnusedValue",
         kwargs: Optional["ChatAzureClientArgs"] = None,
     ):
-        super().__init__(name=name, model=deployment_id)
+        super().__init__(
+            name=name,
+            model=deployment_id,
+            # The OpenAI() constructor will fail if no API key is present.
+            # However, a dummy value is fine -- AzureOpenAI() handles the auth.
+            api_key=api_key or "not-used",
+        )
 
         self._seed = seed
 

{chatlas-0.13.1 → chatlas-0.13.2}/chatlas/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.13.1'
-__version_tuple__ = version_tuple = (0, 13, 1)
+__version__ = version = '0.13.2'
+__version_tuple__ = version_tuple = (0, 13, 2)
 
 __commit_id__ = commit_id = None

{chatlas-0.13.1 → chatlas-0.13.2}/chatlas/types/anthropic/_client.py

@@ -3,7 +3,7 @@
 # ---------------------------------------------------------
 
 
-from typing import Mapping, Optional, TypedDict, Union
+from typing import Mapping, Optional, TypedDict
 
 import anthropic
 import httpx
@@ -13,7 +13,7 @@ class ChatClientArgs(TypedDict, total=False):
     api_key: str | None
     auth_token: str | None
     base_url: str | httpx.URL | None
-    timeout: Union[float, anthropic.Timeout, None, anthropic.NotGiven]
+    timeout: float | anthropic.Timeout | None | anthropic.NotGiven
     max_retries: int
     default_headers: Optional[Mapping[str, str]]
     default_query: Optional[Mapping[str, object]]

{chatlas-0.13.1 → chatlas-0.13.2}/chatlas/types/anthropic/_submit.py

@@ -47,26 +47,24 @@ class SubmitInputArgs(TypedDict, total=False):
         ],
         str,
     ]
-    service_tier: Union[Literal["auto", "standard_only"], anthropic.NotGiven]
-    stop_sequences: Union[Sequence[str], anthropic.NotGiven]
-    stream: Union[Literal[False], Literal[True], anthropic.NotGiven]
+    service_tier: Union[Literal["auto", "standard_only"], anthropic.Omit]
+    stop_sequences: Union[Sequence[str], anthropic.Omit]
+    stream: Union[Literal[False], Literal[True], anthropic.Omit]
     system: Union[
-        str,
-        Iterable[anthropic.types.text_block_param.TextBlockParam],
-        anthropic.NotGiven,
+        str, Iterable[anthropic.types.text_block_param.TextBlockParam], anthropic.Omit
     ]
-    temperature: float | anthropic.NotGiven
+    temperature: float | anthropic.Omit
     thinking: Union[
         anthropic.types.thinking_config_enabled_param.ThinkingConfigEnabledParam,
         anthropic.types.thinking_config_disabled_param.ThinkingConfigDisabledParam,
-        anthropic.NotGiven,
+        anthropic.Omit,
     ]
     tool_choice: Union[
         anthropic.types.tool_choice_auto_param.ToolChoiceAutoParam,
         anthropic.types.tool_choice_any_param.ToolChoiceAnyParam,
         anthropic.types.tool_choice_tool_param.ToolChoiceToolParam,
         anthropic.types.tool_choice_none_param.ToolChoiceNoneParam,
-        anthropic.NotGiven,
+        anthropic.Omit,
     ]
     tools: Union[
         Iterable[
@@ -79,10 +77,10 @@ class SubmitInputArgs(TypedDict, total=False):
                 anthropic.types.web_search_tool_20250305_param.WebSearchTool20250305Param,
             ]
         ],
-        anthropic.NotGiven,
+        anthropic.Omit,
     ]
-    top_k: int | anthropic.NotGiven
-    top_p: float | anthropic.NotGiven
+    top_k: int | anthropic.Omit
+    top_p: float | anthropic.Omit
     extra_headers: Optional[Mapping[str, Union[str, anthropic.Omit]]]
     extra_query: Optional[Mapping[str, object]]
     extra_body: object | None

{chatlas-0.13.1 → chatlas-0.13.2}/chatlas/types/openai/_client.py

@@ -16,7 +16,7 @@ class ChatClientArgs(TypedDict, total=False):
     webhook_secret: str | None
     base_url: str | httpx.URL | None
     websocket_base_url: str | httpx.URL | None
-    timeout: Union[float, openai.Timeout, None, openai.NotGiven]
+    timeout: float | openai.Timeout | None | openai.NotGiven
     max_retries: int
     default_headers: Optional[Mapping[str, str]]
     default_query: Optional[Mapping[str, object]]

{chatlas-0.13.1 → chatlas-0.13.2}/chatlas/types/openai/_submit.py

@@ -108,61 +108,61 @@ class SubmitInputArgs(TypedDict, total=False):
     audio: Union[
         openai.types.chat.chat_completion_audio_param.ChatCompletionAudioParam,
         None,
-        openai.NotGiven,
+        openai.Omit,
     ]
-    frequency_penalty: Union[float, None, openai.NotGiven]
+    frequency_penalty: Union[float, None, openai.Omit]
     function_call: Union[
         Literal["none", "auto"],
         openai.types.chat.chat_completion_function_call_option_param.ChatCompletionFunctionCallOptionParam,
-        openai.NotGiven,
+        openai.Omit,
     ]
     functions: Union[
-        Iterable[openai.types.chat.completion_create_params.Function], openai.NotGiven
+        Iterable[openai.types.chat.completion_create_params.Function], openai.Omit
     ]
-    logit_bias: Union[dict[str, int], None, openai.NotGiven]
-    logprobs: Union[bool, None, openai.NotGiven]
-    max_completion_tokens: Union[int, None, openai.NotGiven]
-    max_tokens: Union[int, None, openai.NotGiven]
-    metadata: Union[dict[str, str], None, openai.NotGiven]
-    modalities: Union[list[Literal["text", "audio"]], None, openai.NotGiven]
-    n: Union[int, None, openai.NotGiven]
-    parallel_tool_calls: bool | openai.NotGiven
+    logit_bias: Union[dict[str, int], None, openai.Omit]
+    logprobs: Union[bool, None, openai.Omit]
+    max_completion_tokens: Union[int, None, openai.Omit]
+    max_tokens: Union[int, None, openai.Omit]
+    metadata: Union[dict[str, str], None, openai.Omit]
+    modalities: Union[list[Literal["text", "audio"]], None, openai.Omit]
+    n: Union[int, None, openai.Omit]
+    parallel_tool_calls: bool | openai.Omit
     prediction: Union[
         openai.types.chat.chat_completion_prediction_content_param.ChatCompletionPredictionContentParam,
         None,
-        openai.NotGiven,
+        openai.Omit,
     ]
-    presence_penalty: Union[float, None, openai.NotGiven]
-    prompt_cache_key: str | openai.NotGiven
+    presence_penalty: Union[float, None, openai.Omit]
+    prompt_cache_key: str | openai.Omit
     reasoning_effort: Union[
-        Literal["minimal", "low", "medium", "high"], None, openai.NotGiven
+        Literal["minimal", "low", "medium", "high"], None, openai.Omit
     ]
     response_format: Union[
         openai.types.shared_params.response_format_text.ResponseFormatText,
         openai.types.shared_params.response_format_json_schema.ResponseFormatJSONSchema,
         openai.types.shared_params.response_format_json_object.ResponseFormatJSONObject,
-        openai.NotGiven,
+        openai.Omit,
     ]
-    safety_identifier: str | openai.NotGiven
-    seed: Union[int, None, openai.NotGiven]
+    safety_identifier: str | openai.Omit
+    seed: Union[int, None, openai.Omit]
     service_tier: Union[
-        Literal["auto", "default", "flex", "scale", "priority"], None, openai.NotGiven
+        Literal["auto", "default", "flex", "scale", "priority"], None, openai.Omit
     ]
-    stop: Union[str, None, Sequence[str], openai.NotGiven]
-    store: Union[bool, None, openai.NotGiven]
-    stream: Union[Literal[False], None, Literal[True], openai.NotGiven]
+    stop: Union[str, None, Sequence[str], openai.Omit]
+    store: Union[bool, None, openai.Omit]
+    stream: Union[Literal[False], None, Literal[True], openai.Omit]
     stream_options: Union[
         openai.types.chat.chat_completion_stream_options_param.ChatCompletionStreamOptionsParam,
         None,
-        openai.NotGiven,
+        openai.Omit,
     ]
-    temperature: Union[float, None, openai.NotGiven]
+    temperature: Union[float, None, openai.Omit]
     tool_choice: Union[
         Literal["none", "auto", "required"],
         openai.types.chat.chat_completion_allowed_tool_choice_param.ChatCompletionAllowedToolChoiceParam,
         openai.types.chat.chat_completion_named_tool_choice_param.ChatCompletionNamedToolChoiceParam,
         openai.types.chat.chat_completion_named_tool_choice_custom_param.ChatCompletionNamedToolChoiceCustomParam,
-        openai.NotGiven,
+        openai.Omit,
     ]
     tools: Union[
         Iterable[
@@ -171,14 +171,14 @@ class SubmitInputArgs(TypedDict, total=False):
                 openai.types.chat.chat_completion_custom_tool_param.ChatCompletionCustomToolParam,
             ]
         ],
-        openai.NotGiven,
+        openai.Omit,
     ]
-    top_logprobs: Union[int, None, openai.NotGiven]
-    top_p: Union[float, None, openai.NotGiven]
-    user: str | openai.NotGiven
-    verbosity: Union[Literal["low", "medium", "high"], None, openai.NotGiven]
+    top_logprobs: Union[int, None, openai.Omit]
+    top_p: Union[float, None, openai.Omit]
+    user: str | openai.Omit
+    verbosity: Union[Literal["low", "medium", "high"], None, openai.Omit]
     web_search_options: (
-        openai.types.chat.completion_create_params.WebSearchOptions | openai.NotGiven
+        openai.types.chat.completion_create_params.WebSearchOptions | openai.Omit
     )
     extra_headers: Optional[Mapping[str, Union[str, openai.Omit]]]
     extra_query: Optional[Mapping[str, object]]

{chatlas-0.13.1 → chatlas-0.13.2}/pyproject.toml

@@ -48,7 +48,11 @@ dev = [
     "matplotlib",
     "Pillow",
     "shiny",
+    "htmltools",
     "shinychat",
+    "narwhals",
+    "pandas",
+    "polars",
     "openai",
     "anthropic[bedrock]",
     "google-genai>=1.14.0",
@@ -58,7 +62,6 @@ dev = [
     "snowflake-ml-python>=1.8.4",
     # torch (a dependency of snowflake-ml-python) is not yet compatible with Python >3.11
     "torch;python_version<='3.11'",
-    "htmltools",
     "tenacity"
 ]
 docs = [

{chatlas-0.13.1 → chatlas-0.13.2}/tests/test_content_tools.py

@@ -1,5 +1,7 @@
 from typing import Any, Optional, Union
+from unittest.mock import Mock
 
+import orjson
 import pytest
 
 from chatlas import ChatOpenAI
@@ -403,3 +405,93 @@ def test_content_tool_request_serializable():
     assert parsed.tool is not None
     assert parsed.tool.name == "add"
     assert parsed.tool.description == "Add two numbers"
+
+
+def test_content_tool_result_pandas_dataframe():
+    """Test ContentToolResult with pandas DataFrame using orient='records'"""
+    pandas = pytest.importorskip("pandas")
+
+    # Create a simple pandas DataFrame
+    df = pandas.DataFrame(
+        {"name": ["Alice", "Bob"], "age": [25, 30], "city": ["New York", "London"]}
+    )
+
+    # Create ContentToolResult with DataFrame value
+    result = ContentToolResult(value=df).get_model_value()
+    expected = df.to_json(orient="records")
+    assert result == expected
+
+    parsed = orjson.loads(str(result))
+    assert isinstance(parsed, list)
+    assert len(parsed) == 2
+    assert parsed[0] == {"name": "Alice", "age": 25, "city": "New York"}
+    assert parsed[1] == {"name": "Bob", "age": 30, "city": "London"}
+
+
+def test_content_tool_result_object_with_to_pandas():
+    """Test ContentToolResult with objects that have .to_pandas() method"""
+    pandas = pytest.importorskip("pandas")
+
+    # Create mock object with to_pandas method (like Polars, PyArrow)
+    mock_df_lib = Mock()
+    pandas_df = pandas.DataFrame({"x": [1, 2, 3], "y": ["a", "b", "c"]})
+    mock_df_lib.to_pandas.return_value = pandas_df
+
+    result = ContentToolResult(value=mock_df_lib).get_model_value()
+    mock_df_lib.to_pandas.assert_called_once()
+    expected = pandas_df.to_json(orient="records")
+    assert result == expected
+
+
+def test_content_tool_result_narwhals_dataframe():
+    """Test ContentToolResult with narwhals DataFrame"""
+    narwhals = pytest.importorskip("narwhals")
+    pandas = pytest.importorskip("pandas")
+
+    pandas_df = pandas.DataFrame({"a": [1, 2], "b": ["x", "y"]})
+    nw_df = narwhals.from_native(pandas_df)
+    result = ContentToolResult(value=nw_df).get_model_value()
+    expected = pandas_df.to_json(orient="records")
+    assert result == expected
+
+
+def test_content_tool_result_object_with_to_dict():
+    """Test ContentToolResult with objects that have to_dict method"""
+    # Mock object with to_dict method but no to_pandas or to_json
+    mock_obj = Mock(spec=["to_dict"])
+    mock_obj.to_dict.return_value = {"key": "value"}
+    result = ContentToolResult(value=mock_obj).get_model_value()
+    mock_obj.to_dict.assert_called_once()
+    # Result should be JSON string representation (orjson format)
+    assert result == '{"key":"value"}'
+
+
+def test_content_tool_result_string_passthrough():
+    """Test ContentToolResult with string values (special case - passed through as-is)"""
+    result = ContentToolResult(value="plain string").get_model_value()
+    assert result == "plain string"
+
+
+def test_content_tool_result_fallback_serialization():
+    """Test ContentToolResult fallback for objects without special methods"""
+    # Regular object without to_json, to_pandas, or to_dict (non-string to avoid the string special case)
+    result = ContentToolResult(value={"key": "value"}).get_model_value()
+    assert result == '{"key":"value"}'
+
+
+def test_content_tool_result_explicit_json_mode():
+    """Test ContentToolResult with explicit JSON mode forces _to_json for non-strings"""
+    # Test with non-string object and explicit JSON mode
+    result = ContentToolResult(
+        value={"key": "value"},
+        model_format="json",
+    ).get_model_value()
+    # With explicit JSON mode, objects get JSON-encoded
+    assert result == '{"key":"value"}'
+    # Test that strings still get special treatment even in JSON mode
+    string_result = ContentToolResult(
+        value="plain string",
+        model_format="json",
+    ).get_model_value()
+    # Strings are still returned as-is even in JSON mode (current behavior)
+    assert string_result == "plain string"

{chatlas-0.13.1 → chatlas-0.13.2}/tests/test_provider_azure.py

@@ -9,14 +9,17 @@ if do_test.lower() == "false":
     pytest.skip("Skipping Azure tests", allow_module_level=True)
 
 
-def test_azure_simple_request():
-    chat = ChatAzureOpenAI(
-        system_prompt="Be as terse as possible; no punctuation",
+def chat_func(system_prompt: str = "Be as terse as possible; no punctuation"):
+    return ChatAzureOpenAI(
+        system_prompt=system_prompt,
         endpoint="https://chatlas-testing.openai.azure.com",
         deployment_id="gpt-4o-mini",
         api_version="2024-08-01-preview",
     )
 
+
+def test_azure_simple_request():
+    chat = chat_func()
     response = chat.chat("What is 1 + 1?")
     assert "2" == response.get_content()
     turn = chat.get_last_turn()
@@ -27,15 +30,20 @@ def test_azure_simple_request():
 
 @pytest.mark.asyncio
 async def test_azure_simple_request_async():
-    chat = ChatAzureOpenAI(
-        system_prompt="Be as terse as possible; no punctuation",
-        endpoint="https://chatlas-testing.openai.azure.com",
-        deployment_id="gpt-4o-mini",
-        api_version="2024-08-01-preview",
-    )
+    chat = chat_func()
 
     response = await chat.chat_async("What is 1 + 1?")
     assert "2" == await response.get_content()
     turn = chat.get_last_turn()
     assert turn is not None
     assert turn.tokens == (27, 2, 0)
+
+
+def test_connect_without_openai_key(monkeypatch):
+    # Ensure OPENAI_API_KEY is not set
+    monkeypatch.delenv("OPENAI_API_KEY", raising=False)
+
+    # This should not raise an error
+    chat = chat_func()
+    assert chat is not None
+

{chatlas-0.13.1 → chatlas-0.13.2}/tests/test_provider_databricks.py

@@ -1,4 +1,5 @@
 import pytest
+
 from chatlas import ChatDatabricks
 
 from .conftest import assert_turns_existing, assert_turns_system
@@ -82,3 +83,12 @@ def test_anthropic_empty_response():
 # def test_openai_pdf():
 #     chat_fun = ChatDatabricks
 #     assert_pdf_local(chat_fun)
+
+
+def test_connect_without_openai_key(monkeypatch):
+    # Ensure OPENAI_API_KEY is not set
+    monkeypatch.delenv("OPENAI_API_KEY", raising=False)
+
+    # This should not raise an error
+    chat = ChatDatabricks()
+    assert chat is not None

{chatlas-0.13.1 → chatlas-0.13.2}/tests/test_tokens.py

@@ -70,7 +70,7 @@ def test_token_count_method():
     chat = ChatAnthropic(model="claude-3-5-sonnet-20241022")
     assert chat.token_count("What is 1 + 1?") == 16
 
-    chat = ChatGoogle(model="gemini-1.5-flash")
+    chat = ChatGoogle(model="gemini-2.5-flash")
     assert chat.token_count("What is 1 + 1?") == 9